legionio 1.4.111 → 1.4.112

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa14ee5aba79a712b64bd58ff53a40076fd8c4d3f84d6b58757f393175aba7f2
-  data.tar.gz: 572ed5d1c54e429da795341b6aa725c9187c06e4dca4445eff530d59f3324f5e
+  metadata.gz: 4543f4e847d248557306e3d6f7675626d9189e2a17d079e23c94df3f58a389d3
+  data.tar.gz: fed3679ff480666c18623114e1f22a618c39357001fa7d8d3f3fa295f2a22f07
 SHA512:
-  metadata.gz: 3eb840d78c0218c25882e8f3e757164ca7463b73f246aec0ac41a99c3c54ab3e644c5f59ee0fd695c0ab31818043f976f765c1316930a4ae86985179f92b69ba
-  data.tar.gz: 338a32c3e8e50b6f4113144b90daf0508a95032ddf3c393317ef1f431671db2d1caf32caf94c5e870181c5cf05e6a483a329bfdb636eacd2b6a4ce646ab34a8b
+  metadata.gz: 9b8bb2eaf61edb8d41812ac9fd1b79abbb4d2d26a0f563b95b42e20d312ae4076c835a53d7c563b0f869db37377ce79682699f01c0d10647be897acc7bb72bb9
+  data.tar.gz: 67db3ddd7c06cf4e77804c040b228cb4319898d510ae9142a9e6d8f477a8f8e7eab8b886444a3356f681088e6d535ffe1f99342b35b7e4efcf6ffc6a9cc8645b

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Legion Changelog
 
+## [1.4.112] - 2026-03-21
+
+### Added
+- `Legion::Lock` distributed locking module (Redis SET NX PX acquire, Lua compare-and-delete release)
+- `Legion::Leader` leader election module with periodic renewal via distributed lock
+- `Legion::Extensions::Actors::Singleton` mixin for singleton actor enforcement (one instance per cluster)
+- `Legion::Leader.reset!` called in shutdown sequence to release leadership before process exit
+
 ## [1.4.111] - 2026-03-21
 
 ### Added

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Actors
+      module Singleton
+        def self.included(base)
+          base.prepend(ExecutionGuard)
+        end
+
+        def singleton_role
+          self.class.name&.gsub('::', '_')&.downcase || 'unknown'
+        end
+
+        def singleton_ttl
+          [time * 3, 30].max
+        end
+
+        module ExecutionGuard
+          def initialize(**opts)
+            @leader_token = nil
+            super
+          end
+
+          private
+
+          def skip_or_run(&)
+            return super unless defined?(Legion::Lock)
+
+            role = singleton_role
+            ttl_ms = singleton_ttl * 1000
+
+            unless @leader_token
+              @leader_token = Legion::Lock.acquire("leader:#{role}", ttl: ttl_ms)
+              return unless @leader_token
+            end
+
+            extended = Legion::Lock.extend_lock("leader:#{role}", @leader_token, ttl: ttl_ms)
+            unless extended
+              @leader_token = Legion::Lock.acquire("leader:#{role}", ttl: ttl_ms)
+              return unless @leader_token
+            end
+
+            super
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -123,6 +123,7 @@ module Legion
             if affinity_result == :remote
               Legion::Logging.debug 'Processing remote-region message ' \
                                     "(region=#{message[:region]}, affinity=#{message[:region_affinity]})"
+              record_cross_region_metric(message)
             end
 
             if use_runner?
@@ -144,6 +145,18 @@ module Legion
 
         private
 
+        def record_cross_region_metric(message)
+          return unless defined?(Legion::Extensions::Telemetry::Runners::Telemetry)
+
+          Legion::Extensions::Telemetry::Runners::Telemetry.record_cross_region(
+            from_region: message[:region],
+            to_region:   Legion::Region.current,
+            affinity:    message[:region_affinity]
+          )
+        rescue StandardError
+          nil
+        end
+
         def check_region_affinity(message)
           return :local unless defined?(Legion::Region)
 

data/lib/legion/leader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+require_relative 'lock'
+
+module Legion
+  module Leader
+    class << self
+      def elect(role, ttl: 30)
+        ttl_ms = ttl * 1000
+        token = Legion::Lock.acquire("leader:#{role}", ttl: ttl_ms)
+        return nil unless token
+
+        @leaders ||= {}
+        @leaders[role.to_sym] = { token: token, ttl_ms: ttl_ms }
+        token
+      end
+
+      def leader?(role)
+        return false unless @leaders&.dig(role.to_sym, :token)
+
+        Legion::Lock.locked?("leader:#{role}")
+      end
+
+      def resign(role)
+        return false unless @leaders&.dig(role.to_sym)
+
+        entry = @leaders.delete(role.to_sym)
+        stop_renewal(role)
+        Legion::Lock.release("leader:#{role}", entry[:token])
+      end
+
+      def with_leadership(role, ttl: 30)
+        token = elect(role, ttl: ttl)
+        raise Legion::Lock::NotAcquired, "could not elect leader for: #{role}" unless token
+
+        start_renewal(role, ttl)
+        yield
+      ensure
+        resign(role)
+      end
+
+      def reset!
+        @leaders&.each_key { |role| resign(role) }
+        @leaders = {}
+        @renewals&.each_value(&:shutdown)
+        @renewals = {}
+      end
+
+      private
+
+      def start_renewal(role, ttl)
+        @renewals ||= {}
+        interval = [ttl / 3, 1].max
+        entry = @leaders[role.to_sym]
+        return unless entry
+
+        @renewals[role.to_sym] = Concurrent::TimerTask.new(execution_interval: interval) do
+          success = Legion::Lock.extend_lock("leader:#{role}", entry[:token], ttl: entry[:ttl_ms])
+          unless success
+            log_warn("Lost leadership for #{role}")
+            @renewals[role.to_sym]&.shutdown
+          end
+        end
+        @renewals[role.to_sym].execute
+      end
+
+      def stop_renewal(role)
+        @renewals ||= {}
+        @renewals.delete(role.to_sym)&.shutdown
+      end
+
+      def log_warn(msg)
+        Legion::Logging.warn(msg) if defined?(Legion::Logging)
+      end
+    end
+  end
+end

data/lib/legion/lock.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Lock
+    class NotAcquired < StandardError; end
+
+    RELEASE_SCRIPT = <<~LUA
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+      else
+        return 0
+      end
+    LUA
+
+    EXTEND_SCRIPT = <<~LUA
+      if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("pexpire", KEYS[1], ARGV[2])
+      else
+        return 0
+      end
+    LUA
+
+    class << self
+      def acquire(name, ttl: 30_000)
+        token = SecureRandom.uuid
+        key = lock_key(name)
+        result = with_redis { |conn| conn.set(key, token, nx: true, px: ttl) }
+        result ? token : nil
+      rescue StandardError
+        nil
+      end
+
+      def release(name, token)
+        key = lock_key(name)
+        result = with_redis { |conn| conn.eval(RELEASE_SCRIPT, keys: [key], argv: [token]) }
+        result == 1
+      rescue StandardError
+        false
+      end
+
+      def with_lock(name, ttl: 30_000)
+        token = acquire(name, ttl: ttl)
+        raise NotAcquired, "could not acquire lock: #{name}" unless token
+
+        yield
+      ensure
+        release(name, token) if token
+      end
+
+      def extend_lock(name, token, ttl: 30_000)
+        key = lock_key(name)
+        result = with_redis { |conn| conn.eval(EXTEND_SCRIPT, keys: [key], argv: [token, ttl.to_s]) }
+        result == 1
+      rescue StandardError
+        false
+      end
+
+      def locked?(name)
+        with_redis { |conn| conn.exists?(lock_key(name)) }
+      rescue StandardError
+        false
+      end
+
+      private
+
+      def lock_key(name)
+        "legion:lock:#{name}"
+      end
+
+      def with_redis(&)
+        Legion::Cache.client.with(&)
+      end
+    end
+  end
+end

data/lib/legion/service.rb

@@ -254,6 +254,7 @@ module Legion
     def register_logging_hooks
       return unless Legion::Transport::Connection.session_open?
 
+      require 'legion/transport/exchanges/logging' unless defined?(Legion::Transport::Exchanges::Logging)
       exchange = Legion::Transport::Exchanges::Logging.new
 
       %i[fatal error warn].each do |level|
@@ -381,6 +382,8 @@ module Legion
       Legion::Data.shutdown if Legion::Settings[:data][:connected]
       Legion::Readiness.mark_not_ready(:data)
 
+      Legion::Leader.reset! if defined?(Legion::Leader)
+
       Legion::Cache.shutdown
       Legion::Readiness.mark_not_ready(:cache)
 

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.4.111'
+  VERSION = '1.4.112'
 end

data/lib/legion.rb

@@ -13,6 +13,8 @@ require 'legion/extensions'
 
 module Legion
   autoload :Region, 'legion/region'
+  autoload :Lock,   'legion/lock'
+  autoload :Leader, 'legion/leader'
 
   attr_reader :service
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.4.111
+  version: 1.4.112
 platform: ruby
 authors:
 - Esity
@@ -614,6 +614,7 @@ files:
 - lib/legion/extensions/actors/nothing.rb
 - lib/legion/extensions/actors/once.rb
 - lib/legion/extensions/actors/poll.rb
+- lib/legion/extensions/actors/singleton.rb
 - lib/legion/extensions/actors/subscription.rb
 - lib/legion/extensions/builders/actors.rb
 - lib/legion/extensions/builders/base.rb
@@ -644,7 +645,9 @@ files:
 - lib/legion/helpers/context.rb
 - lib/legion/ingress.rb
 - lib/legion/isolation.rb
+- lib/legion/leader.rb
 - lib/legion/lex.rb
+- lib/legion/lock.rb
 - lib/legion/metrics.rb
 - lib/legion/notebook/generator.rb
 - lib/legion/notebook/parser.rb