schked 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a45abd806085b8336543dfff30a298b8f1148e0ee0642cd4896b8e6f5a721c3
-  data.tar.gz: b2d6030f651c9a86e573038c88a30f26efbd6bc840ff212aab9baa5cbb3b4fab
+  metadata.gz: 4d392bfee50671c6bc87ab00b4cbdb29969e55544d35a6133ce23b24f1d3171e
+  data.tar.gz: 196a09231bd9abb1c0a83f7d4d6d4ecb140cb3b305e1710aa775f21690ae3eb7
 SHA512:
-  metadata.gz: 8a13bb8431aaf97845d49c92e8410dc65d8a3308cb34ce129ce060c3dea5673fbc254c3bdcb461a1e4049020d71dbd16894fd0fe25be1fd53faab491b0077f36
-  data.tar.gz: 18289f5de7000436ebfc4249b3b2de3781dcf61873c94442d93584f3e362652bcef7ede7ba4e08355692f3a4d479cd149579ca19b3c99360c632787defdf23e9
+  metadata.gz: '02810b0f6a3717db6e4f5aa4cee9eee4644c74c7a583fbc1c0e6acae97d63193366c1ecbd0ee087106acbe542a49ace4e5cdfe209aba0b11c3d31938ef088638'
+  data.tar.gz: b55de68f347b8be57cc32cbf13ef582cd4ac33c8cddb881bfcead7bc449454953147c20bd311a03bfaa38c444884e6bf45daa7b54d2bb4bcbad5e2207d50194e

data/README.md

@@ -124,6 +124,54 @@ config/initializers/schked.rb
 Schked.config.logger = Logger.new(Rails.root.join("log", "schked.log"))
 ```
 
+### Liveness probe
+
+Schked can expose a small HTTP endpoint for Kubernetes liveness probes. It is **disabled by default** to keep the existing behavior unchanged.
+
+Configure it in Ruby:
+
+```ruby
+Schked.config.liveness_probe = {
+  enabled: true,
+  bind: "0.0.0.0",
+  port: 8080,
+  path: "/healthz",
+  heartbeat_interval: 5,
+  heartbeat_threshold: 15
+}
+```
+
+Or via CLI flags:
+
+```sh
+bundle exec schked start --liveness-probe --liveness-bind 0.0.0.0 --liveness-port 8080 --liveness-path /healthz
+```
+
+In Rails, set it through the application config:
+
+```ruby
+# config/application.rb or config/environments/*.rb
+config.schked.liveness_probe = {
+  enabled: true,
+  bind: "0.0.0.0",
+  port: 8080,
+  path: "/healthz",
+  heartbeat_interval: 5,
+  heartbeat_threshold: 15
+}
+```
+
+The endpoint returns `200 OK` while the scheduler is responsive and `503 Service Unavailable` when the heartbeat is stale or during shutdown. The scheduler updates the heartbeat every `heartbeat_interval` seconds (default `5`); if it is not updated within `heartbeat_threshold` seconds (default `15`), the endpoint reports unhealthy. Use it in Kubernetes like this:
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 8080
+  initialDelaySeconds: 10
+  periodSeconds: 10
+```
+
 ### Monitoring
 
 [Yabeda::Schked](https://github.com/yabeda-rb/yabeda-schked) - built-in metrics for monitoring Schked recurring jobs out of the box! Part of the [yabeda](https://github.com/yabeda-rb/yabeda) suite.

data/lib/schked/cli.rb

@@ -15,7 +15,7 @@ module Schked
           .shellsplit
       end
 
-      super(argv)
+      super
     end
 
     def self.exit_on_failure?
@@ -26,8 +26,13 @@ module Schked
 
     desc "start", "Start scheduler"
     option :require, type: :array
+    option :liveness_probe, type: :boolean, default: nil, desc: "Enable or disable the liveness probe"
+    option :liveness_bind, type: :string, desc: "Address the liveness probe binds to"
+    option :liveness_port, type: :numeric, desc: "Port the liveness probe listens on"
+    option :liveness_path, type: :string, desc: "HTTP path for the liveness probe"
     def start
       load_requires
+      apply_liveness_probe_options
 
       Schked.worker.wait
     end
@@ -50,5 +55,15 @@ module Schked
       # We have to load Schked at here, because of Rails and our railtie.
       require "schked"
     end
+
+    def apply_liveness_probe_options
+      overrides = {}
+      overrides[:enabled] = options[:liveness_probe] unless options[:liveness_probe].nil?
+      overrides[:bind] = options[:liveness_bind] if options[:liveness_bind]
+      overrides[:port] = options[:liveness_port] if options[:liveness_port]
+      overrides[:path] = options[:liveness_path] if options[:liveness_path]
+
+      Schked.config.liveness_probe = Schked.config.liveness_probe.to_h.merge(overrides) if overrides.any?
+    end
   end
 end

data/lib/schked/config.rb

@@ -9,6 +9,14 @@ module Schked
       :redis,
       :standalone
 
+    def liveness_probe
+      @liveness_probe ||= LivenessProbeConfig.new
+    end
+
+    def liveness_probe=(value)
+      @liveness_probe = value.is_a?(LivenessProbeConfig) ? value : LivenessProbeConfig.new(value)
+    end
+
     def paths
       @paths ||= []
     end

data/lib/schked/liveness_probe.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "socket"
+require "ipaddr"
+
+module Schked
+  class LivenessProbeConfig
+    attr_reader :enabled, :bind, :port, :path, :heartbeat_interval, :heartbeat_threshold
+
+    DEFAULTS = {
+      enabled: false,
+      bind: "0.0.0.0",
+      port: 8080,
+      path: "/healthz",
+      heartbeat_interval: 5,
+      heartbeat_threshold: 15
+    }.freeze
+
+    def initialize(attrs = {})
+      attrs = DEFAULTS.merge(attrs)
+
+      @enabled = !!attrs[:enabled]
+      @bind = validate_bind(attrs[:bind])
+      @port = validate_port(attrs[:port])
+      @path = validate_path(attrs[:path])
+      @heartbeat_interval = validate_positive_integer(attrs[:heartbeat_interval], :heartbeat_interval)
+      @heartbeat_threshold = validate_threshold(attrs[:heartbeat_threshold], attrs[:heartbeat_interval])
+    end
+
+    def to_h
+      {
+        enabled: enabled,
+        bind: bind,
+        port: port,
+        path: path,
+        heartbeat_interval: heartbeat_interval,
+        heartbeat_threshold: heartbeat_threshold
+      }
+    end
+
+    private
+
+    def validate_bind(value)
+      value = value.to_s
+      raise ArgumentError, "Schked liveness_probe `bind` must be non-empty" if value.empty?
+
+      IPAddr.new(value)
+      value
+    rescue IPAddr::InvalidAddressError
+      raise ArgumentError, "Schked liveness_probe `bind` is invalid: #{value}"
+    end
+
+    def validate_port(value)
+      port = Integer(value)
+      raise ArgumentError, "Schked liveness_probe `port` must be between 1 and 65535, got: #{port}" unless port.between?(1, 65_535)
+
+      port
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "Schked liveness_probe `port` must be an integer between 1 and 65535, got: #{value.inspect}"
+    end
+
+    def validate_path(value)
+      value = value.to_s
+      raise ArgumentError, "Schked liveness_probe `path` must start with /, got: #{value}" unless value.start_with?("/")
+
+      value
+    end
+
+    def validate_positive_integer(value, name)
+      int = Integer(value)
+      raise ArgumentError, "Schked liveness_probe `#{name}` must be a positive integer, got: #{int}" unless int.positive?
+
+      int
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "Schked liveness_probe `#{name}` must be a positive integer, got: #{value.inspect}"
+    end
+
+    def validate_threshold(value, interval)
+      int = validate_positive_integer(value, :heartbeat_threshold)
+      interval = validate_positive_integer(interval, :heartbeat_interval)
+      raise ArgumentError, "Schked liveness_probe `heartbeat_threshold` must be >= heartbeat_interval" if int < interval
+
+      int
+    end
+  end
+
+  class LivenessProbe
+    attr_reader :config, :logger
+
+    def initialize(config:, logger:)
+      @config = config
+      @logger = logger
+      @last_heartbeat_at = nil
+      @shutting_down = false
+      @server = nil
+      @thread = nil
+      @mutex = Mutex.new
+    end
+
+    def start
+      return unless config.enabled
+
+      @server = create_server
+      logger.info("Schked liveness probe listening on #{config.bind}:#{config.port}#{config.path}")
+
+      @thread = Thread.new {
+        Thread.current.name = "schked-liveness-probe" if Thread.current.respond_to?(:name=)
+        accept_loop
+      }
+    end
+
+    def heartbeat
+      @last_heartbeat_at = Time.now
+    end
+
+    def stop
+      @mutex.synchronize do
+        return if @shutting_down
+
+        @shutting_down = true
+      end
+
+      sleep 0.1
+      @server&.close
+      @thread&.join(5)
+      logger.info("Schked liveness probe stopped")
+    end
+
+    def healthy?
+      return false if @shutting_down
+      return false if @last_heartbeat_at.nil?
+
+      Time.now - @last_heartbeat_at <= config.heartbeat_threshold
+    end
+
+    private
+
+    def create_server
+      TCPServer.new(config.bind, config.port)
+    rescue Errno::EADDRINUSE => e
+      raise ArgumentError, "Schked liveness probe port #{config.port} is already in use on #{config.bind}: #{e.message}"
+    end
+
+    def accept_loop
+      loop do
+        client = @server.accept
+
+        Thread.new(client) do |conn|
+          handle_client(conn)
+        end
+      rescue IOError, Errno::EBADF
+        break
+      end
+    end
+
+    def handle_client(client)
+      request_line = read_request_line(client)
+      return if request_line.nil?
+
+      _method, path, _protocol = request_line.split(" ", 3)
+
+      response = response_for(path)
+      client.print(response)
+    ensure
+      begin
+        client.close
+      rescue IOError
+        # already closed
+      end
+    end
+
+    def read_request_line(client)
+      return nil unless IO.select([client], nil, nil, 5)
+
+      client.gets
+    end
+
+    def response_for(path)
+      if path == config.path
+        if healthy?
+          "HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: 2\r\nConnection: close\r\n\r\nOK"
+        else
+          "HTTP/1.1 503 Service Unavailable\r\nContent-Type: text/plain\r\nContent-Length: 11\r\nConnection: close\r\n\r\nUnavailable"
+        end
+      else
+        "HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n"
+      end
+    end
+  end
+end

data/lib/schked/railtie.rb

@@ -4,6 +4,8 @@ require "rails/railtie"
 
 module Schked
   class Railtie < Rails::Railtie
+    config.schked = ActiveSupport::OrderedOptions.new
+
     class PathsConfig
       def self.call(app)
         return if Schked.config.do_not_load_root_schedule?
@@ -16,7 +18,15 @@ module Schked
       end
     end
 
+    class LivenessConfig
+      def self.call(app)
+        liveness_probe = app.config.schked.liveness_probe
+        Schked.config.liveness_probe = liveness_probe if liveness_probe
+      end
+    end
+
     initializer("schked.paths", &PathsConfig.method(:call))
+    initializer("schked.liveness", after: :load_config_initializers) { |app| LivenessConfig.call(app) }
 
     config.to_prepare do
       Schked.config.logger = ::Rails.logger unless Schked.config.logger?

data/lib/schked/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Schked
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/schked/worker.rb

@@ -6,6 +6,7 @@ module Schked
   class Worker
     def initialize(config:)
       @config = config
+      @liveness_probe = nil
 
       @locker = RedisLocker.new(config.redis, lock_ttl: 40_000, logger: config.logger) unless config.standalone?
 
@@ -15,6 +16,7 @@ module Schked
       define_callbacks
       define_extend_lock unless config.standalone?
       load_schedule
+      start_liveness_probe
     end
 
     def job(as)
@@ -30,6 +32,7 @@ module Schked
     end
 
     def stop
+      liveness_probe&.stop
       scheduler.stop
     end
 
@@ -44,7 +47,7 @@ module Schked
 
     private
 
-    attr_reader :config, :scheduler, :locker
+    attr_reader :config, :scheduler, :locker, :liveness_probe
 
     def define_callbacks
       cfg = config
@@ -94,7 +97,10 @@ module Schked
 
       Thread.new do
         loop do
-          scheduler.shutdown(wait: 5) if @shutdown
+          if @shutdown
+            liveness_probe&.stop
+            scheduler.shutdown(wait: 5)
+          end
           sleep 1
         end
       end
@@ -109,5 +115,18 @@ module Schked
     def load_schedule
       scheduler.instance_eval(schedule)
     end
+
+    def start_liveness_probe
+      return unless config.liveness_probe.enabled
+
+      @liveness_probe = LivenessProbe.new(config: config.liveness_probe, logger: config.logger)
+      @liveness_probe.start
+
+      scheduler.every("#{config.liveness_probe.heartbeat_interval}s", as: "Schked::Worker#liveness_heartbeat", overlap: false) do
+        @liveness_probe.heartbeat
+      end
+
+      @liveness_probe.heartbeat
+    end
   end
 end

data/lib/schked.rb

@@ -4,6 +4,7 @@ require "connection_pool"
 require "redlock"
 
 require "schked/version"
+require "schked/liveness_probe"
 require "schked/config"
 require "schked/worker"
 require "schked/redis_locker"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schked
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Misha Merkushin
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
@@ -175,14 +189,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1.37'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '1.37'
 description: Rufus-scheduler wrapper to run recurring jobs
 email:
 - merkushin.m.s@gmail.com
@@ -197,6 +211,7 @@ files:
 - lib/schked.rb
 - lib/schked/cli.rb
 - lib/schked/config.rb
+- lib/schked/liveness_probe.rb
 - lib/schked/railtie.rb
 - lib/schked/redis_client_factory.rb
 - lib/schked/redis_locker.rb