activejob-temporal 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79166555209f6e6cf73641c9415feac14e6cffad299940c94ebcba0568c3cfdd
-  data.tar.gz: 4e3f843f44c93c4ce383415b32616f7770c407dec314dbf5e305a820e9095480
+  metadata.gz: ebc4386d6eac6522fba437fbdbd136334a3b5c333f6f83ad90fbfbaab5664144
+  data.tar.gz: 53cc07919979a66c013f6dd9597064cc73929ee8930a05c351774883760a1b59
 SHA512:
-  metadata.gz: f1dd16daf2739bbefdb568eb08423ca071fdc4ef96cee1b775d1fbb383728abec3c226d4f52d1ee633db6b7048ae5e6d68c0842a72dedf40cb03fdb4fe7d41ca
-  data.tar.gz: 9c17b2bf542f9990b68db645b32edd0176d8250309e70577d583f7d2102ed5cf176000ad5a5384a51c5ac4aa58fd18af161c226f389af413d66a0b00f01c84bd
+  metadata.gz: 652237c25d9342062bebd8269328f684c2cfc1d7a630cdbe0c5be9ae0a2f7d6bce0a96f48cd47de8dbad8da7a9fe5dbbf0974cfa7b92a3a646789c4e25c78873
+  data.tar.gz: 6503e062254a40daae4d00a97fa66a312e2d57d127c2cecd13218468ec73b9eecc168f8c3f2dcdc7734fb089f4f9b0ea7b53f4369f8e11ee0934ab4e0d05a143

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-07
+
+### Added
+- Configuration now fails to validate when `api_key` or `api_key_file` is set while `tls` is left unset. The Temporal SDK enables TLS on its own whenever an API key is present, so leaving `tls` at `nil` silently coupled transport security to an unrelated setting and failed the handshake against a plaintext frontend.
+- The client logs `credential_source_shadowed` when two sources for the same credential are configured (`api_key` alongside `api_key_file`, or `tls` alongside the `tls_*_path` settings). Precedence was already defined but silent.
+
+### Changed
+- **Breaking:** `tls_cert_watch` and `api_key_watch` are replaced by a single `credential_watch`, default `true`. A file path is only configured because the credential behind it rotates, so watching every configured credential file is now the default instead of two opt-in flags that could each be forgotten.
+- **Breaking:** `tls_reload_signal` is renamed `reload_signal` (`ACTIVEJOB_TEMPORAL_TLS_RELOAD_SIGNAL` becomes `ACTIVEJOB_TEMPORAL_RELOAD_SIGNAL`). It rebuilds the whole client and re-resolves the API key, not just TLS material.
+- **Breaking:** `CredentialRefresher.from_config` no longer accepts `on_api_key_change`. Applying a rotated token mutates the live connection, so it is the same call in every process and had no caller that overrode it.
+
+### Documentation
+- `CredentialRefresher.from_config` and the worker setup guide now state that a process running its own `Temporalio::Worker` must pass `on_tls_change`. The default `reload_client!` closes the client it replaces, which is the one such a worker is still polling on. `bin/temporal-worker` already passes it.
+
+### Migration from 0.4.x
+- Rename `tls_cert_watch` / `api_key_watch` to `credential_watch`, or drop them: watching is on by default and applies to whatever credential files are configured.
+- Rename `tls_reload_signal` to `reload_signal`, and `ACTIVEJOB_TEMPORAL_TLS_RELOAD_SIGNAL` to `ACTIVEJOB_TEMPORAL_RELOAD_SIGNAL`.
+- Set `tls` explicitly wherever `api_key` or `api_key_file` is configured: `config.tls = false` for a plaintext in-cluster frontend, `config.tls = true` for Temporal Cloud. Boot now fails until you do.
+- Drop `on_api_key_change:` from any `CredentialRefresher.from_config` call.
+
+## [0.4.0] - 2026-08-07
+
+### Added
+- `credential_poll_interval` (default 30 seconds) and `credential_file_events` (default false) configure how `tls_cert_watch` and `api_key_watch` detect rotation.
+- `ActiveJob::Temporal::CredentialRefresher` replaces `CertificateWatcher`. Enqueue-side processes can now start it from an initializer instead of scheduling `refresh_api_key!` themselves - see [worker setup](docs/worker_setup.md#api-key-authentication).
+
+### Changed
+- Credential rotation is detected by comparing a content digest on an interval rather than by filesystem events. Rotation on mounts whose events never reach the process (or where the `listen` gem is absent) now works, at up to one poll interval of latency. `credential_file_events = true` restores immediate reaction by waking the check early; it never decides whether a reload happens, so a missing `listen` gem costs latency, not correctness.
+- A cert and key pair rotating together now triggers one client rebuild instead of a debounced pair, and TLS plus API key watching share a single watcher instead of two.
+- **Breaking:** `ActiveJob::Temporal::CertificateWatcher` is removed. Applications constructing it directly should use `CredentialRefresher.from_config`.
+
+### Fixed
+- Watching a Kubernetes projected or secret volume no longer prints listen's `directory is already being watched!` error at boot. kubelet keeps the live secret in a timestamped sibling of the `..data` symlink, so listen's recursive scan reached the same real directory twice; the versioned copy is now skipped.
+
 ## [0.3.1] - 2026-08-06
 
 ### Fixed

data/activejob-temporal.gemspec

@@ -39,6 +39,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency "globalid", ">= 0.3"
   spec.add_dependency "temporalio", ">= 1.4.0", "< 1.7"
 
+  # listen is an optional runtime dependency, required lazily only when credential_file_events is
+  # enabled. Without it credentials still rotate, just on the poll interval instead of instantly.
   spec.add_development_dependency "benchmark-ips", "~> 2.14"
   spec.add_development_dependency "github_changelog_generator", "~> 1.18"
   spec.add_development_dependency "listen", "~> 3.9"

data/bin/temporal-worker

@@ -107,11 +107,11 @@ if pool_size < 1
   exit(1)
 end
 
-reload_signal = config.tls_reload_signal.to_s.sub(/\ASIG/i, "").upcase
+reload_signal = config.reload_signal.to_s.sub(/\ASIG/i, "").upcase
 unless Signal.list.key?(reload_signal) && !ActiveJob::Temporal::UNTRAPPABLE_SIGNALS.include?(reload_signal)
   warn(
-    "Error: ACTIVEJOB_TEMPORAL_TLS_RELOAD_SIGNAL must be a signal name safe to trap, " \
-    "got: #{config.tls_reload_signal.inspect}"
+    "Error: ACTIVEJOB_TEMPORAL_RELOAD_SIGNAL must be a signal name safe to trap, " \
+    "got: #{config.reload_signal.inspect}"
   )
   exit(1)
 end
@@ -260,25 +260,14 @@ reload_signal_thread = Thread.new do
 end
 Signal.trap(reload_signal) { reload_signal_queue.push(reload_signal) }
 
-certificate_watcher = nil
-if config.tls_cert_watch
-  certificate_watcher = ActiveJob::Temporal::CertificateWatcher.new(
-    paths: ActiveJob::Temporal::CertificateWatcher.paths_from_config(config),
-    # Failures are logged by the reloader and retried by the watcher, so let them propagate.
-    reload_callback: -> { client_reloader.reload(source: "file_watch") }
-  ).start
-end
-
-# Token rotation mutates the live connection (the SDK sends the header per-RPC from the
-# connection's stored options) - no client rebuild, unlike certificate rotation above.
-# Configuration validation guarantees api_key_file is set when api_key_watch is on.
-api_key_watcher = nil
-if config.api_key_watch
-  api_key_watcher = ActiveJob::Temporal::CertificateWatcher.new(
-    paths: [config.api_key_file],
-    reload_callback: -> { ActiveJob::Temporal.refresh_api_key! }
-  ).start
-end
+# Only the TLS callback is overridden: certificate rotation has to swap the rebuilt client into
+# the running worker, while token rotation mutates the live connection (the SDK sends the header
+# per-RPC from the connection's stored options) and needs no worker awareness.
+credential_refresher = ActiveJob::Temporal::CredentialRefresher.from_config(
+  config,
+  # Failures are logged by the reloader and retried on the next check, so let them propagate.
+  on_tls_change: -> { client_reloader.reload(source: "credential_refresh") }
+).start
 
 begin
   worker_health.mark_started!
@@ -290,8 +279,7 @@ rescue Interrupt
   # Temporal worker raises Interrupt on shutdown signals; swallow to allow clean exit.
 ensure
   worker_health.mark_stopped!
-  certificate_watcher&.stop
-  api_key_watcher&.stop
+  credential_refresher.stop
   reload_signal_queue.close
   reload_signal_thread.join(1)
   health_check_server&.stop

data/lib/activejob/temporal/client.rb

@@ -8,6 +8,7 @@ rescue LoadError
 end
 
 require_relative "tls_file"
+require_relative "logger"
 
 module ActiveJob
   module Temporal
@@ -121,6 +122,8 @@ module ActiveJob
       def connection_kwargs(configuration)
         kwargs = {}
 
+        warn_on_shadowed_credentials(configuration)
+
         tls = tls_options(configuration)
         kwargs[:tls] = tls unless tls.nil?
 
@@ -131,6 +134,37 @@ module ActiveJob
       end
       private_class_method :connection_kwargs
 
+      # Every credential has more than one possible source and the precedence between them is
+      # silent, so a config that sets two looks like it works while one of them is ignored.
+      # @api private
+      def warn_on_shadowed_credentials(configuration)
+        if credential_present?(configuration, :api_key) && credential_present?(configuration, :api_key_file)
+          Logger.warn("credential_source_shadowed", credential: "api_key", ignored: "api_key_file")
+        end
+
+        return unless configuration.respond_to?(:tls) && !configuration.tls.nil?
+        return if tls_path_attributes(configuration).empty?
+
+        Logger.warn(
+          "credential_source_shadowed",
+          credential: "tls",
+          ignored: tls_path_attributes(configuration).join(", ")
+        )
+      end
+      private_class_method :warn_on_shadowed_credentials
+
+      def credential_present?(configuration, attribute)
+        configuration.respond_to?(attribute) && configuration.public_send(attribute).to_s.strip != ""
+      end
+      private_class_method :credential_present?
+
+      def tls_path_attributes(configuration)
+        %i[tls_cert_path tls_key_path tls_server_root_ca_cert_path].select do |attribute|
+          credential_present?(configuration, attribute)
+        end
+      end
+      private_class_method :tls_path_attributes
+
       # Resolves the API key: an explicit api_key wins, otherwise api_key_file is read - at
       # connection build time, and again by {ActiveJob::Temporal.refresh_api_key!} when the
       # token file rotates.

data/lib/activejob/temporal/configuration.rb

@@ -122,18 +122,12 @@ module ActiveJob
         description: "Optional TLS SNI domain override"
       },
 
-      tls_cert_watch: {
-        default: false,
-        env_var: "ACTIVEJOB_TEMPORAL_TLS_CERT_WATCH",
-        type: :boolean,
-        description: "Watch TLS certificate files and reload worker clients when they change"
-      },
-
-      tls_reload_signal: {
+      reload_signal: {
         default: "HUP",
-        env_var: "ACTIVEJOB_TEMPORAL_TLS_RELOAD_SIGNAL",
+        env_var: "ACTIVEJOB_TEMPORAL_RELOAD_SIGNAL",
         type: :string,
-        description: "Signal used by workers to reload TLS certificates manually"
+        description: "Signal used by workers to rebuild the Temporal client manually, picking up " \
+                     "rotated TLS material and a rotated API key"
       },
 
       api_key: {
@@ -151,12 +145,28 @@ module ActiveJob
                      "projected Kubernetes ServiceAccount token. An explicit api_key takes precedence"
       },
 
-      api_key_watch: {
+      credential_watch: {
+        default: true,
+        env_var: "ACTIVEJOB_TEMPORAL_CREDENTIAL_WATCH",
+        type: :boolean,
+        description: "Keep every configured credential file fresh: api_key_file and the TLS " \
+                     "certificate paths. A file path exists because the credential rotates, so " \
+                     "this is on by default and watches whatever paths are configured"
+      },
+
+      credential_poll_interval: {
+        default: 30,
+        env_var: "ACTIVEJOB_TEMPORAL_CREDENTIAL_POLL_INTERVAL",
+        type: :integer,
+        description: "Seconds between credential file checks when credential_watch is enabled"
+      },
+
+      credential_file_events: {
         default: false,
-        env_var: "ACTIVEJOB_TEMPORAL_API_KEY_WATCH",
+        env_var: "ACTIVEJOB_TEMPORAL_CREDENTIAL_FILE_EVENTS",
         type: :boolean,
-        description: "Watch api_key_file and refresh the token when it changes (kubelet rotates " \
-                     "projected tokens atomically, long before they expire)"
+        description: "React to credential file changes immediately instead of waiting for the next " \
+                     "poll (requires the optional listen gem; the poll interval stays the safety net)"
       },
 
       priority_task_queues: {
@@ -752,6 +762,7 @@ module ActiveJob
       validate :validate_payload_storage_settings
       validate :validate_tls_settings
       validate :validate_api_key_settings
+      validate :validate_credential_refresh_settings
       validate :validate_worker_registration_settings
       validate :validate_local_activity_helpers
       validate :validate_dependency_wait_settings
@@ -1038,8 +1049,18 @@ module ActiveJob
         validate_tls_file_path(:tls_key_path)
         validate_tls_file_path(:tls_server_root_ca_cert_path)
         validate_tls_domain
-        validate_tls_cert_watch
-        validate_tls_reload_signal
+        validate_tls_decision
+        validate_reload_signal
+      end
+
+      # The Temporal SDK turns TLS on by itself whenever an api_key is present, so leaving `tls`
+      # unset silently couples transport security to an unrelated setting - and fails at connect
+      # against a plaintext in-cluster frontend. Make the caller state the intent instead.
+      def validate_tls_decision
+        return unless tls.nil?
+        return if api_key.to_s.strip.empty? && api_key_file.to_s.strip.empty?
+
+        errors.add(:tls, :requires_explicit_choice)
       end
 
       def validate_tls_cert_key_pair
@@ -1068,28 +1089,22 @@ module ActiveJob
         errors.add(:tls_domain, :blank)
       end
 
-      def validate_tls_cert_watch
-        unless [true, false].include?(tls_cert_watch)
-          errors.add(:tls_cert_watch, :not_boolean, value: tls_cert_watch.inspect)
-          return
-        end
-
-        return unless tls_cert_watch && tls_watch_paths.empty?
-
-        errors.add(:tls_cert_watch, :requires_paths)
-      end
-
       def validate_api_key_settings
         validate_tls_file_path(:api_key_file)
+      end
 
-        unless [true, false].include?(api_key_watch)
-          errors.add(:api_key_watch, :not_boolean, value: api_key_watch.inspect)
-          return
+      def validate_credential_refresh_settings
+        unless [true, false].include?(credential_watch)
+          errors.add(:credential_watch, :not_boolean, value: credential_watch.inspect)
+        end
+
+        unless [true, false].include?(credential_file_events)
+          errors.add(:credential_file_events, :not_boolean, value: credential_file_events.inspect)
         end
 
-        return unless api_key_watch && api_key_file.to_s.strip.empty?
+        return if credential_poll_interval.is_a?(Integer) && credential_poll_interval.positive?
 
-        errors.add(:api_key_watch, :requires_path)
+        errors.add(:credential_poll_interval, :invalid, value: credential_poll_interval.inspect)
       end
 
       def validate_worker_registration_settings
@@ -1103,20 +1118,16 @@ module ActiveJob
         errors.add(:worker_activejob_workloads, :requires_activities)
       end
 
-      def validate_tls_reload_signal
-        unless tls_reload_signal.is_a?(String) && tls_reload_signal.strip.present?
-          errors.add(:tls_reload_signal, :blank)
+      def validate_reload_signal
+        unless reload_signal.is_a?(String) && reload_signal.strip.present?
+          errors.add(:reload_signal, :blank)
           return
         end
 
-        normalized_signal = tls_reload_signal.sub(/\ASIG/i, "").upcase
+        normalized_signal = reload_signal.sub(/\ASIG/i, "").upcase
         return if Signal.list.key?(normalized_signal) && !UNTRAPPABLE_SIGNALS.include?(normalized_signal)
 
-        errors.add(:tls_reload_signal, :invalid, value: tls_reload_signal.inspect)
-      end
-
-      def tls_watch_paths
-        [tls_cert_path, tls_key_path, tls_server_root_ca_cert_path].compact.reject { |path| path.to_s.strip.empty? }
+        errors.add(:reload_signal, :invalid, value: reload_signal.inspect)
       end
 
       def callable_accepts_positional_job?(callable)

data/lib/activejob/temporal/credential_refresher.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../temporal"
+
+module ActiveJob
+  module Temporal
+    # Keeps credential files fresh in a long-lived process: TLS material, API key files, or
+    # anything else read once at boot and rotated underneath the process later.
+    #
+    # Change detection is a content digest compared on an interval, so the only thing that can fire
+    # a callback is the bytes behind a path actually differing. Filesystem events (see :file_events)
+    # are an optional accelerator that wakes the loop early; they never decide whether a reload
+    # happens, so a missing `listen` gem or a mount without working inotify costs latency, not
+    # correctness.
+    #
+    # @example Worker: rebuild the client on cert rotation, patch the live connection on token rotation
+    #   refresher = CredentialRefresher.from_config(
+    #     ActiveJob::Temporal.config,
+    #     on_tls_change: -> { client_reloader.reload(source: "credential_refresh") }
+    #   ).start
+    #
+    # @example Enqueue-side process (web, Sidekiq) with a rotating projected token
+    #   require "activejob/temporal/credential_refresher"
+    #   ActiveJob::Temporal::CredentialRefresher.from_config(ActiveJob::Temporal.config).start
+    class CredentialRefresher
+      # kubelet keeps the live secret in a timestamped sibling of `..data`, so listen's recursive
+      # scan reaches the same real directory twice and prints a SymlinkLoop error to stderr.
+      # Getting this wrong costs that stderr noise and nothing else: listen only ever nudges the
+      # loop, so the digest still decides, and the interval still backs it up.
+      #
+      # @api private
+      KUBERNETES_VERSIONED_DIR = /\A\.\.\d/
+      private_constant :KUBERNETES_VERSIONED_DIR
+
+      DEFAULT_POLL_INTERVAL = 30
+
+      # Files digested as one unit. Cert and key rotate as separate writes, so grouping them turns
+      # a rotation into a single callback instead of a pair.
+      Source = Struct.new(:name, :paths, :on_change, keyword_init: true)
+
+      class << self
+        # Builds a refresher for every credential file the configuration names. A path is only
+        # configured because the credential behind it rotates, so `credential_watch` gates the
+        # whole mechanism rather than each file individually.
+        #
+        # A token refresh mutates the live connection, so it is the same call in every process.
+        # A certificate refresh is not: the default rebuilds the memoized client, which is right
+        # for an enqueue-side process but wrong inside a worker.
+        #
+        # @note A process running a `Temporalio::Worker` MUST pass `on_tls_change`. The worker holds
+        #   its own client reference, and the default `reload_client!` closes the client it replaces
+        #   - which is the one the worker is still polling on. Pass a callback that assigns the fresh
+        #   client to the worker, as {WorkerClientReloader} does.
+        #
+        # @param configuration [Configuration] the gem configuration
+        # @param on_tls_change [#call] invoked when any TLS file changes; see the note above
+        # @param logger [#log_event, #warn, #error] structured logger
+        # @param listener_factory [#to, nil] injection point for tests, defaults to `Listen`
+        # @return [CredentialRefresher] a refresher with no sources when no credential file is
+        #   configured, or when `credential_watch` is off
+        def from_config(configuration,
+                        on_tls_change: -> { ActiveJob::Temporal.reload_client! },
+                        logger: ActiveJob::Temporal::Logger,
+                        listener_factory: nil)
+          sources = []
+
+          if configuration.credential_watch
+            tls = tls_paths(configuration)
+            sources << Source.new(name: "tls", paths: tls, on_change: on_tls_change) if tls.any?
+
+            token = configuration.api_key_file.to_s.strip
+            if token.present?
+              sources << Source.new(name: "api_key", paths: [token],
+                                    on_change: -> { ActiveJob::Temporal.refresh_api_key! })
+            end
+          end
+
+          new(
+            sources: sources,
+            poll_interval: configuration.credential_poll_interval,
+            file_events: configuration.credential_file_events,
+            logger: logger,
+            listener_factory: listener_factory
+          )
+        end
+
+        # @param configuration [Configuration] the gem configuration
+        # @return [Array<String>] configured TLS file paths, blanks removed
+        def tls_paths(configuration)
+          [
+            configuration.tls_cert_path,
+            configuration.tls_key_path,
+            configuration.tls_server_root_ca_cert_path
+          ].compact.reject { |path| path.to_s.strip.empty? }
+        end
+      end
+
+      # @param sources [Array<Source>] credential groups to keep fresh
+      # @param poll_interval [Integer, Float] seconds between digest comparisons
+      # @param file_events [Boolean] wake the loop early on filesystem events, requires `listen`
+      # @param logger [#log_event, #warn, #error] structured logger
+      # @param listener_factory [#to, nil] injection point for tests, defaults to `Listen`
+      def initialize(sources:, poll_interval: DEFAULT_POLL_INTERVAL, file_events: false,
+                     logger: ActiveJob::Temporal::Logger, listener_factory: nil)
+        @sources = sources.reject { |source| source.paths.compact.empty? }
+        @poll_interval = poll_interval
+        @file_events = file_events
+        @logger = logger
+        @listener_factory = listener_factory
+        @wakeups = Thread::Queue.new
+        @digests = {}
+        @thread = nil
+        @listener = nil
+      end
+
+      # Baselines each digest before polling, so a process booting on an already-rotated file does
+      # not fire a redundant reload on its first check.
+      #
+      # @return [self]
+      def start
+        return self if @sources.empty? || @thread
+
+        @sources.each { |source| @digests[source.name] = digest(source) }
+        @thread = Thread.new { run }
+        start_listener if @file_events
+        self
+      end
+
+      # @return [void]
+      def stop
+        @listener&.stop
+        @listener = nil
+        @wakeups.close
+        @thread&.join
+        @thread = nil
+      end
+
+      # Re-reads every source and fires the callbacks whose content changed. Safe to call at any
+      # rate: unchanged content is a no-op.
+      #
+      # @return [void]
+      def refresh_changed_sources
+        @sources.each { |source| refresh(source) }
+      end
+
+      # Wakes the poll loop so the next comparison happens now instead of on the next tick.
+      # Decides nothing on its own.
+      #
+      # @return [void]
+      def nudge
+        @wakeups << :wakeup
+      rescue ClosedQueueError
+        nil
+      end
+
+      private
+
+      def run
+        until @wakeups.closed?
+          @wakeups.pop(timeout: @poll_interval)
+          break if @wakeups.closed?
+
+          # A rotation emits a burst of events; collapse them into the single check that follows.
+          @wakeups.clear
+          refresh_changed_sources
+        end
+      end
+
+      def refresh(source)
+        current = digest(source)
+        return if current.nil? || current == @digests[source.name]
+
+        source.on_change.call
+        # Stamped only after the callback succeeds, so a failed reload is retried on the next tick.
+        @digests[source.name] = current
+        @logger.log_event("credential_refreshed", source: source.name)
+      rescue StandardError => e
+        @logger.error(
+          "credential_refresh_failed",
+          source: source.name,
+          error_class: e.class.name,
+          message: e.message
+        )
+      end
+
+      # A path can be briefly unreadable while kubelet swaps the mount. Treat that as "no reading"
+      # so the next tick retries, rather than reloading against a half-written credential.
+      def digest(source)
+        contents = source.paths.compact.map { |path| TLSFile.read(path) }
+        Digest::SHA256.hexdigest(contents.join("\0"))
+      rescue TLSFile::Error
+        nil
+      end
+
+      def start_listener
+        @listener = listener_factory.to(*watched_directories, ignore: KUBERNETES_VERSIONED_DIR) { nudge }
+        @listener.start
+      rescue LoadError => e
+        # Polling already guarantees the refresh, so a missing listen gem is a latency
+        # regression rather than a boot failure.
+        @logger.warn(
+          "credential_file_events_unavailable",
+          error_class: e.class.name,
+          message: e.message,
+          poll_interval_seconds: @poll_interval
+        )
+      end
+
+      def watched_directories
+        @sources.flat_map(&:paths).compact.map { |path| File.dirname(File.expand_path(path)) }.uniq
+      end
+
+      def listener_factory
+        @listener_factory ||= begin
+          require "listen"
+          Listen
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/locales/en.yml

@@ -129,11 +129,10 @@ en:
             tls_domain:
               blank: "must be present when configured"
 
-            tls_cert_watch:
-              not_boolean: "must be true or false, got: %{value}"
-              requires_paths: "requires at least one TLS certificate path to watch"
+            tls:
+              requires_explicit_choice: "must be set explicitly to true, false, or TLS options when api_key or api_key_file is configured - the Temporal SDK enables TLS on its own whenever an API key is present, which fails the handshake against a plaintext frontend"
 
-            tls_reload_signal:
+            reload_signal:
               blank: "must be present when configured"
               invalid: "must be a signal name like HUP or USR1, got: %{value}"
 
@@ -141,9 +140,14 @@ en:
               invalid_path: "must be a non-empty file path, got: %{value}"
               unreadable_path: "must resolve to a readable regular file, got: %{value}"
 
-            api_key_watch:
+            credential_watch:
+              not_boolean: "must be true or false, got: %{value}"
+
+            credential_poll_interval:
+              invalid: "must be a positive number of seconds, got: %{value}"
+
+            credential_file_events:
               not_boolean: "must be true or false, got: %{value}"
-              requires_path: "requires api_key_file to watch"
 
             worker_activejob_workloads:
               not_boolean: "must be true or false, got: %{value}"

data/lib/activejob/temporal/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveJob
   module Temporal
-    VERSION = "0.3.1"
+    VERSION = "0.5.0"
   end
 end

data/lib/activejob/temporal/worker_runtime.rb

@@ -2,7 +2,7 @@
 
 require_relative "../temporal"
 require_relative "rails_environment_loader"
-require_relative "certificate_watcher"
+require_relative "credential_refresher"
 require_relative "reload_signal_queue"
 require_relative "worker_client_reloader"
 require_relative "worker_pool"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activejob-temporal
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Temporal Technologies
@@ -309,7 +309,6 @@ files:
 - lib/activejob/temporal/cancel.rb
 - lib/activejob/temporal/cancel/batch_canceller.rb
 - lib/activejob/temporal/cancel/batch_summary.rb
-- lib/activejob/temporal/certificate_watcher.rb
 - lib/activejob/temporal/chain_options.rb
 - lib/activejob/temporal/child_workflow_options.rb
 - lib/activejob/temporal/client.rb
@@ -318,6 +317,7 @@ files:
 - lib/activejob/temporal/configuration.rb
 - lib/activejob/temporal/configured_job_compatibility.rb
 - lib/activejob/temporal/connection_worker_pool.rb
+- lib/activejob/temporal/credential_refresher.rb
 - lib/activejob/temporal/dead_letter_payload_validation.rb
 - lib/activejob/temporal/dead_letter_queue.rb
 - lib/activejob/temporal/dependency_options.rb

data/lib/activejob/temporal/certificate_watcher.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveJob
-  module Temporal
-    # Watches TLS certificate files and runs a reload callback when they change.
-    class CertificateWatcher
-      DEFAULT_DEBOUNCE_SECONDS = 1.0
-
-      def self.paths_from_config(configuration)
-        [
-          configuration.tls_cert_path,
-          configuration.tls_key_path,
-          configuration.tls_server_root_ca_cert_path
-        ].compact.reject { |path| path.to_s.strip.empty? }
-      end
-
-      def initialize(paths:, reload_callback:, listener_factory: nil, debounce_seconds: DEFAULT_DEBOUNCE_SECONDS)
-        @paths = paths.map { |path| File.expand_path(path) }.uniq
-        @reload_callback = reload_callback
-        @listener_factory = listener_factory
-        @debounce_seconds = debounce_seconds
-        @mutex = Mutex.new
-        @last_reload_at = nil
-        @listener = nil
-        @trailing_reload = nil
-      end
-
-      def start
-        return self if @paths.empty? || @listener
-
-        @listener = listener_factory.to(*directories) do |modified, added, removed|
-          handle_changes(modified + added + removed)
-        end
-        @listener.start
-        self
-      end
-
-      def stop
-        @listener&.stop
-        @listener = nil
-        @mutex.synchronize { @trailing_reload }&.kill
-      end
-
-      def handle_changes(changed_paths)
-        return unless relevant_change?(changed_paths)
-
-        if debounced?
-          schedule_trailing_reload
-        else
-          reload(retry_on_failure: true)
-        end
-      end
-
-      private
-
-      # A failed reload clears the debounce stamp so the next change reloads
-      # immediately, and gets one retry in case no further change arrives.
-      def reload(retry_on_failure:)
-        @reload_callback.call
-      rescue StandardError
-        @mutex.synchronize { @last_reload_at = nil }
-        schedule_trailing_reload if retry_on_failure
-      end
-
-      # Cert and key rotate as separate writes, so the second one lands inside
-      # the debounce window. Flush it once the window closes instead of dropping it.
-      def schedule_trailing_reload
-        @mutex.synchronize do
-          return if @trailing_reload&.alive?
-
-          @trailing_reload = Thread.new do
-            sleep(@debounce_seconds)
-            @mutex.synchronize { @last_reload_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) }
-            reload(retry_on_failure: false)
-          end
-        end
-      end
-
-      def directories
-        @directories ||= @paths.map { |path| File.dirname(path) }.uniq
-      end
-
-      def listener_factory
-        @listener_factory ||= begin
-          require "listen"
-          Listen
-        rescue LoadError => e
-          raise LoadError, "listen gem is required when tls_cert_watch is enabled: #{e.message}"
-        end
-      end
-
-      # Kubernetes projected and secret volumes rotate atomically: kubelet writes a new timestamped
-      # directory and swaps a `..data` symlink, so the watched file's own path never appears in the
-      # change events. Any change inside a watched file's directory therefore counts as relevant;
-      # the debounce absorbs the multi-event burst a rotation produces.
-      def relevant_change?(changed_paths)
-        changed_paths.any? do |path|
-          expanded = File.expand_path(path)
-          @paths.include?(expanded) || directories.any? { |dir| expanded.start_with?("#{dir}/") }
-        end
-      end
-
-      def debounced?
-        return false unless @debounce_seconds.positive?
-
-        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        @mutex.synchronize do
-          return true if @last_reload_at && (now - @last_reload_at) < @debounce_seconds
-
-          @last_reload_at = now
-          false
-        end
-      end
-    end
-  end
-end