kicks_liveness 0.1.1 → 0.1.3

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.1'.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'
@@ -9,8 +10,8 @@ require_relative 'kicks_liveness/hooks'
 # Liveness probe for Kicks and Sneakers workers, backed by a tmpfs heartbeat.
 #
 # The worker publishes a mark from inside its own process, checking its Bunny
-# consumers in memory; the probe reads only the mark's mtime. No Rails, no call
-# to the broker.
+# consumers in memory; the probe reads only the container generation and mark
+# mtimes. No Rails, no call to the broker.
 #
 # @see file:docs/SETUP.md
 # @see file:docs/DESIGN.md
@@ -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.1
+  version: 0.1.3
 platform: ruby
 authors:
 - PoroshkinaVV
@@ -11,12 +11,8 @@ date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   A liveness probe for RabbitMQ worker pods that loads no Rails and never talks
-  to the broker. The worker publishes a heartbeat to tmpfs from inside its own
-  process, checking its Bunny consumers in memory; the probe only reads the
-  file's mtime and runs as `bundle exec kicks-liveness`. It loads no application
-  code; aside from Bundler and the interpreter it loads only the gem's small
-  probe files, while the state itself comes from tmpfs. A broker hiccup cannot
-  restart every replica at once.
+  to the broker. Workers check their Bunny consumers in memory and publish a
+  heartbeat to tmpfs; the probe only reads that heartbeat.
 email:
 - lera.poroshkina@mail.ru
 executables:
@@ -43,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.1
+  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'