kicks_liveness 0.1.2 → 0.1.3

data/lib/kicks_liveness/registry.rb

@@ -14,11 +14,8 @@ module KicksLiveness
     class << self
       # Records a worker as subscribed.
       #
-      # Registering the same object twice would break the size comparison in
-      # {healthy?} and leave the process permanently unhealthy, so identity is
-      # checked first. +equal?+ rather than +==+ on purpose: this is a registry
-      # of objects, and a worker class is free to define equality however it
-      # likes.
+      # Duplicate objects must not inflate the expected-count check. Use identity
+      # rather than == because worker classes can override equality.
       #
       # @param worker [Sneakers::Worker]
       # @return [Array] the registry
@@ -36,16 +33,7 @@ module KicksLiveness
         @mutex.synchronize { @workers.delete(worker) }
       end
 
-      # @return [Integer] how many workers are currently registered
-      def size
-        @mutex.synchronize { @workers.size }
-      end
-
-      # Records that this process is shutting down on purpose.
-      #
-      # Without it a graceful shutdown is indistinguishable from a failure: the
-      # registry empties as each worker unsubscribes, so the monitor would see
-      # an incomplete set and report a genuine fault on every deploy.
+      # Mark deliberate shutdown before unsubscription changes the predicate.
       #
       # @return [true]
       def stopping!

data/lib/kicks_liveness/topology_report.rb

@@ -0,0 +1,110 @@
+require 'fileutils'
+
+module KicksLiveness
+  # Claims worker topology reports across fork respawns. Kept outside
+  # {Heartbeat} because the probe does not report these diagnostics.
+  #
+  # @see file:docs/LIMITATIONS.md#container-generations-need-linux-procfs-and-a-private-pid-namespace
+  # @api private
+  class TopologyReport
+    # @param dir [String] marks directory
+    # @param topology [ContainerGeneration::Result] what this worker proved
+    def initialize(dir, topology)
+      @dir = dir
+      @topology = topology
+    end
+
+    # Claims the right to report this state, once.
+    #
+    # Unverifiable results use a generation key; unavailable and unsafe results
+    # have no trustworthy generation and use only their state. Verification
+    # clears the flag so a later degradation can be reported again.
+    #
+    # @return [Array(Symbol, String), nil] the level and the line to log, or nil
+    #   when there is nothing new to say
+    def claim!
+      key = key_for(@topology)
+
+      unless key
+        forget! if @topology.verified?
+        return nil
+      end
+
+      return nil unless claim(key)
+
+      report_for(@topology)
+    end
+
+    private
+
+    def path
+      File.join(@dir, 'topology-report')
+    end
+
+    def key_for(topology)
+      case topology.state
+      when :unsafe then 'unsafe'
+      when :unverifiable then "unverifiable #{topology.generation}"
+      when :unavailable then 'unavailable'
+      end
+    end
+
+    # Only unsafe changes the probe verdict and is reported at ERROR.
+    def report_for(topology)
+      case topology.state
+      when :unsafe
+        [:error, "#{Heartbeat::UNSUPPORTED_TOPOLOGY} (#{topology.detail}); " \
+                 'liveness probes fail until the pod is recreated without those settings']
+      when :unverifiable
+        [:warn, "PID topology unverified (#{topology.detail}): the container generation still scopes the heartbeat, " \
+                'but shareProcessNamespace and hostPID cannot be ruled out']
+      else
+        [:warn, "no container generation (#{topology.detail}): falling back to freshness only, " \
+                'which cannot reject a heartbeat inherited from a previous container']
+      end
+    end
+
+    # The runner starts all of its forks together, so the read and write have
+    # to be one inter-process operation: an atomic rename protects readers from
+    # a partial file, but does not stop every fork reading the old key and each
+    # claiming the same report. The state file is also the lock file, so no
+    # second path is added to the marks contract. Once it has existed it is
+    # cleared by truncation rather than unlink: every process must keep locking
+    # the same inode.
+    def claim(key)
+      synchronize(create: true) do |state|
+        state.rewind
+        next false if state.read.chomp == key
+
+        state.rewind
+        state.truncate(0)
+        state.write("#{key}\n")
+        state.flush
+        true
+      end
+    rescue StandardError
+      # A report that cannot be remembered must still be made. The cost is
+      # repetition on the next start, not silence about a lost guarantee.
+      true
+    end
+
+    def forget!
+      return unless File.exist?(path)
+
+      synchronize(create: false) { |state| state.truncate(0) }
+    rescue StandardError
+      nil
+    end
+
+    def synchronize(create:)
+      FileUtils.mkdir_p(@dir)
+      flags = File::RDWR
+      flags |= File::CREAT if create
+      File.open(path, flags, 0o644) do |state|
+        raise IOError, "cannot lock #{path}" unless state.flock(File::LOCK_EX)
+
+        yield state
+      end
+    end
+  end
+end

data/lib/kicks_liveness/version.rb

@@ -1,4 +1,4 @@
 module KicksLiveness
   # @return [String] gem version
-  VERSION = '0.1.2'.freeze
+  VERSION = '0.1.3'.freeze
 end

data/lib/kicks_liveness.rb

@@ -1,6 +1,7 @@
 require_relative 'kicks_liveness/version'
 require_relative 'kicks_liveness/heartbeat'
 require_relative 'kicks_liveness/attempts'
+require_relative 'kicks_liveness/topology_report'
 require_relative 'kicks_liveness/configuration'
 require_relative 'kicks_liveness/registry'
 require_relative 'kicks_liveness/monitor'
@@ -76,7 +77,8 @@ module KicksLiveness
     # @param slot [Integer] supervisor slot of this fork
     # @param processes [Integer] how many forks the probe must wait for
     # @param consumers [Integer] how many workers must subscribe here
-    # @return [Thread, nil] nil when disabled by configuration
+    # @return [Thread, nil] nil when disabled by configuration, or when the PID
+    #   topology is proven unsupported
     # @api private
     def start!(slot:, processes:, consumers:)
       return unless config.enabled?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kicks_liveness
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - PoroshkinaVV
@@ -39,13 +39,14 @@ files:
 - lib/kicks_liveness/probe.rb
 - lib/kicks_liveness/railtie.rb
 - lib/kicks_liveness/registry.rb
+- lib/kicks_liveness/topology_report.rb
 - lib/kicks_liveness/version.rb
 homepage: https://github.com/PoroshkinaVV/kicks_liveness
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/PoroshkinaVV/kicks_liveness
-  documentation_uri: https://rubydoc.info/gems/kicks_liveness/0.1.2
+  documentation_uri: https://rubydoc.info/gems/kicks_liveness/0.1.3
   changelog_uri: https://github.com/PoroshkinaVV/kicks_liveness/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/PoroshkinaVV/kicks_liveness/issues
   rubygems_mfa_required: 'true'