lex-tick 0.1.10 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec291267e8b58c191d7031607b05b5f6f09081bb5cf3eeb797dcecf46237419d
-  data.tar.gz: 709792c3d29424ebaed1cf5bdb1bd914b7a8723b0f693a37d896e4a35d0836de
+  metadata.gz: 39bbb25a91bd1c83e768654add47baa2a81e429635a223a88fa9d23df45f7c84
+  data.tar.gz: 68b89d858df59af162e15c60b1a8e8f416e6b9e28ad6aa2b2ced4d51beade459
 SHA512:
-  metadata.gz: b157b24e3ecffc0ea09c999e01b4d5e7921ff1170dc480926923193453d89a3bdbcc64846379c456933ddd6ef7a2073118f89ae5d3fed6003a7a8f6f2eeb29ae
-  data.tar.gz: 200d06d265ef64b11bace9864c267a7997900421fd59ebf5c114edf8eb245a5929e1c31942055c6040fdbbe16b836f91a83d264271fd2db9e0d8a582b83d9ac9
+  metadata.gz: 9ecf69a533a7e2781dd9253d1d6575fe58615c4b189e33aac1950d84b605710f43ee8e351c3483886bdcc9a35b54ca908ad1d62326e4ab8339a07144bfdcc12c
+  data.tar.gz: 26911dfa59621334936c5a197b32eec2f6a918c3d23bab1fe35123342750759b7a6a4fa945b3d05ed726d6cc9541585efccf7dd36e5114f2877a50ce1a421248

data/lib/legion/extensions/tick/actors/tick.rb

@@ -10,10 +10,11 @@ module Legion
         # Cortex wires phase_handlers from all agentic extensions
         # and calls execute_tick with real handlers instead of empty ones.
         # To use tick standalone (without cortex), re-enable this actor.
-        class Tick < Legion::Extensions::Actors::Every # rubocop:disable Legion/Extension/EveryActorRequiresTime
+        class Tick < Legion::Extensions::Actors::Every
           def initialize(**opts)
             return unless enabled?
 
+            apply_initial_jitter
             super
           end
 
@@ -52,6 +53,15 @@ module Legion
           def args
             { signals: [], phase_handlers: {} }
           end
+
+          private
+
+          def apply_initial_jitter
+            return unless Helpers::Jitter.jitter_enabled?
+
+            offset = Helpers::Jitter.deterministic_jitter(self.class.name.to_s, time)
+            sleep(offset) if offset.positive?
+          end
         end
       end
     end

data/lib/legion/extensions/tick/helpers/jitter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Tick
+      module Helpers
+        module Jitter
+          MAX_JITTER_CAP = 900 # seconds (15 minutes)
+
+          module_function
+
+          # Returns a deterministic integer jitter offset (seconds) for the given task name
+          # and interval. The offset is in the range [0, max_jitter) where max_jitter is
+          # 10% of the interval, capped at MAX_JITTER_CAP (15 minutes).
+          #
+          # The same task_name always produces the same offset, so all nodes handling the
+          # same named task will sleep the same initial amount — preventing thundering herd
+          # while keeping execution predictable.
+          def deterministic_jitter(task_name, interval_seconds)
+            max_jitter = [interval_seconds * 0.1, MAX_JITTER_CAP].min.to_i
+            return 0 if max_jitter < 1
+
+            task_name.to_s.hash.abs % max_jitter
+          end
+
+          # Returns true when jitter is enabled via settings (default: true).
+          def jitter_enabled?
+            setting = begin
+              Legion::Settings[:tick]
+            rescue StandardError => _e
+              nil
+            end
+            return true if setting.nil?
+
+            tick_hash = setting.is_a?(Hash) ? setting : nil
+            return true if tick_hash.nil?
+
+            tick_hash.fetch(:jitter_enabled, true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/tick/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Tick
-      VERSION = '0.1.10'
+      VERSION = '0.1.11'
     end
   end
 end

data/lib/legion/extensions/tick.rb

@@ -2,6 +2,7 @@
 
 require 'legion/extensions/tick/version'
 require 'legion/extensions/tick/helpers/constants'
+require 'legion/extensions/tick/helpers/jitter'
 require 'legion/extensions/tick/helpers/state'
 require 'legion/extensions/tick/runners/orchestrator'
 

data/spec/legion/extensions/tick/actors/tick_spec.rb

@@ -16,6 +16,9 @@ $LOADED_FEATURES << 'legion/extensions/actors/every'
 require 'legion/extensions/tick/actors/tick'
 
 RSpec.describe Legion::Extensions::Tick::Actor::Tick do
+  # Prevent real sleep calls in all examples; jitter tests override this per-context
+  before { allow_any_instance_of(described_class).to receive(:sleep) }
+
   subject(:actor) { described_class.new }
 
   describe '#initialize' do
@@ -101,4 +104,47 @@ RSpec.describe Legion::Extensions::Tick::Actor::Tick do
       expect(actor.args).to eq({ signals: [], phase_handlers: {} })
     end
   end
+
+  describe 'initial jitter behavior' do
+    context 'when jitter is enabled and offset is positive' do
+      before do
+        allow(Legion::Extensions::Tick::Helpers::Jitter).to receive(:jitter_enabled?).and_return(true)
+        allow(Legion::Extensions::Tick::Helpers::Jitter).to receive(:deterministic_jitter).and_return(5)
+      end
+
+      it 'sleeps for the jitter offset during initialization' do
+        slept = nil
+        allow_any_instance_of(described_class).to receive(:sleep) { |_obj, secs| slept = secs }
+        described_class.new
+        expect(slept).to eq(5)
+      end
+    end
+
+    context 'when jitter offset is zero' do
+      before do
+        allow(Legion::Extensions::Tick::Helpers::Jitter).to receive(:jitter_enabled?).and_return(true)
+        allow(Legion::Extensions::Tick::Helpers::Jitter).to receive(:deterministic_jitter).and_return(0)
+      end
+
+      it 'does not call sleep' do
+        sleep_called = false
+        allow_any_instance_of(described_class).to receive(:sleep) { sleep_called = true }
+        described_class.new
+        expect(sleep_called).to be false
+      end
+    end
+
+    context 'when jitter is disabled' do
+      before do
+        allow(Legion::Extensions::Tick::Helpers::Jitter).to receive(:jitter_enabled?).and_return(false)
+      end
+
+      it 'does not call sleep' do
+        sleep_called = false
+        allow_any_instance_of(described_class).to receive(:sleep) { sleep_called = true }
+        described_class.new
+        expect(sleep_called).to be false
+      end
+    end
+  end
 end

data/spec/legion/extensions/tick/helpers/jitter_spec.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Tick::Helpers::Jitter do
+  describe '.deterministic_jitter' do
+    it 'returns the same value for the same task name and interval' do
+      a = described_class.deterministic_jitter('my_task', 60)
+      b = described_class.deterministic_jitter('my_task', 60)
+      expect(a).to eq(b)
+    end
+
+    it 'returns different values for different task names' do
+      a = described_class.deterministic_jitter('task_alpha', 600)
+      b = described_class.deterministic_jitter('task_beta', 600)
+      # Different names should almost always differ (hash collision is astronomically rare)
+      # but we assert the function is at least defined and returns integers
+      expect(a).to be_a(Integer)
+      expect(b).to be_a(Integer)
+    end
+
+    it 'returns a value within the 10% bound of the interval' do
+      interval = 600
+      max_jitter = (interval * 0.1).to_i
+      jitter = described_class.deterministic_jitter('interval_actor', interval)
+      expect(jitter).to be >= 0
+      expect(jitter).to be < max_jitter
+    end
+
+    it 'caps jitter at MAX_JITTER_CAP (900 seconds) regardless of interval' do
+      jitter = described_class.deterministic_jitter('large_interval_actor', 100_000)
+      expect(jitter).to be < described_class::MAX_JITTER_CAP
+    end
+
+    it 'returns 0 for very small intervals where 10% rounds to < 1 second' do
+      expect(described_class.deterministic_jitter('tiny_task', 5)).to eq(0)
+      expect(described_class.deterministic_jitter('tiny_task', 1)).to eq(0)
+    end
+
+    it 'returns 0 for a zero interval' do
+      expect(described_class.deterministic_jitter('zero_task', 0)).to eq(0)
+    end
+
+    it 'accepts a symbol task name without raising' do
+      expect { described_class.deterministic_jitter(:symbol_task, 120) }.not_to raise_error
+    end
+
+    it 'produces an integer result' do
+      result = described_class.deterministic_jitter('my_task', 300)
+      expect(result).to be_a(Integer)
+    end
+  end
+
+  describe '.jitter_enabled?' do
+    context 'when Legion::Settings is not available or returns nil' do
+      before do
+        allow(Legion::Settings).to receive(:[]).with(:tick).and_return(nil)
+      end
+
+      it 'defaults to true' do
+        expect(described_class.jitter_enabled?).to be true
+      end
+    end
+
+    context 'when settings return a hash with jitter_enabled: true' do
+      before do
+        allow(Legion::Settings).to receive(:[]).with(:tick).and_return({ jitter_enabled: true })
+      end
+
+      it 'returns true' do
+        expect(described_class.jitter_enabled?).to be true
+      end
+    end
+
+    context 'when settings return a hash with jitter_enabled: false' do
+      before do
+        allow(Legion::Settings).to receive(:[]).with(:tick).and_return({ jitter_enabled: false })
+      end
+
+      it 'returns false' do
+        expect(described_class.jitter_enabled?).to be false
+      end
+    end
+
+    context 'when settings raise a StandardError' do
+      before do
+        allow(Legion::Settings).to receive(:[]).with(:tick).and_raise(StandardError)
+      end
+
+      it 'defaults to true' do
+        expect(described_class.jitter_enabled?).to be true
+      end
+    end
+
+    context 'when settings return a non-hash value' do
+      before do
+        allow(Legion::Settings).to receive(:[]).with(:tick).and_return('invalid')
+      end
+
+      it 'defaults to true' do
+        expect(described_class.jitter_enabled?).to be true
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-tick
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.11
 platform: ruby
 authors:
 - Esity
@@ -121,12 +121,14 @@ files:
 - lib/legion/extensions/tick/actors/tick.rb
 - lib/legion/extensions/tick/client.rb
 - lib/legion/extensions/tick/helpers/constants.rb
+- lib/legion/extensions/tick/helpers/jitter.rb
 - lib/legion/extensions/tick/helpers/state.rb
 - lib/legion/extensions/tick/runners/orchestrator.rb
 - lib/legion/extensions/tick/version.rb
 - spec/legion/extensions/tick/actors/tick_spec.rb
 - spec/legion/extensions/tick/client_spec.rb
 - spec/legion/extensions/tick/helpers/constants_spec.rb
+- spec/legion/extensions/tick/helpers/jitter_spec.rb
 - spec/legion/extensions/tick/helpers/state_spec.rb
 - spec/legion/extensions/tick/runners/orchestrator_open_inference_spec.rb
 - spec/legion/extensions/tick/runners/orchestrator_spec.rb