activejob-temporal 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e1e7c38c2a169353b2d9f7edadca0614e32cb6c8c33ed87fe1d29b72a7dd5cb
-  data.tar.gz: 3255fbe711eac898e2b91a65fa2bc5f858eccda59e605774fa027a6a2ba72291
+  metadata.gz: ebc4386d6eac6522fba437fbdbd136334a3b5c333f6f83ad90fbfbaab5664144
+  data.tar.gz: 53cc07919979a66c013f6dd9597064cc73929ee8930a05c351774883760a1b59
 SHA512:
-  metadata.gz: b722896482be5075f145926ad914fedd43b860d438c0badf855f030aaa501d6839233315e0427b841e24d108e89fe775375f77e8e07f8ac983f43169eac383cd
-  data.tar.gz: 6f40349c1961652d0f4c1e242a383895264cf585a2a6bcf127e3ed6dc66f9025413a664289d3ac05325ed9f10dab0d3f427c240af600555dfab8fb50d37f46fc
+  metadata.gz: 652237c25d9342062bebd8269328f684c2cfc1d7a630cdbe0c5be9ae0a2f7d6bce0a96f48cd47de8dbad8da7a9fe5dbbf0974cfa7b92a3a646789c4e25c78873
+  data.tar.gz: 6503e062254a40daae4d00a97fa66a312e2d57d127c2cecd13218468ec73b9eecc168f8c3f2dcdc7734fb089f4f9b0ea7b53f4369f8e11ee0934ab4e0d05a143

data/CHANGELOG.md

@@ -7,6 +7,26 @@ 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

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

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,19 +145,20 @@ module ActiveJob
                      "projected Kubernetes ServiceAccount token. An explicit api_key takes precedence"
       },
 
-      api_key_watch: {
-        default: false,
-        env_var: "ACTIVEJOB_TEMPORAL_API_KEY_WATCH",
+      credential_watch: {
+        default: true,
+        env_var: "ACTIVEJOB_TEMPORAL_CREDENTIAL_WATCH",
         type: :boolean,
-        description: "Watch api_key_file and refresh the token when it changes (kubelet rotates " \
-                     "projected tokens atomically, long before they expire)"
+        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 tls_cert_watch or api_key_watch is enabled"
+        description: "Seconds between credential file checks when credential_watch is enabled"
       },
 
       credential_file_events: {
@@ -1054,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
@@ -1084,31 +1089,15 @@ 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)
-
-        unless [true, false].include?(api_key_watch)
-          errors.add(:api_key_watch, :not_boolean, value: api_key_watch.inspect)
-          return
-        end
-
-        return unless api_key_watch && api_key_file.to_s.strip.empty?
-
-        errors.add(:api_key_watch, :requires_path)
       end
 
       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
@@ -1129,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

@@ -40,29 +40,40 @@ module ActiveJob
       Source = Struct.new(:name, :paths, :on_change, keyword_init: true)
 
       class << self
-        # Builds a refresher from the `tls_cert_watch` / `api_key_watch` configuration flags.
-        # The callbacks default to the process-wide reload paths, which is what an enqueue-side
-        # process wants; workers override the TLS one so the running worker gets the new client.
+        # 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
-        # @param on_api_key_change [#call] invoked when the API key file changes
+        # @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 both flags are off
+        # @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! },
-                        on_api_key_change: -> { ActiveJob::Temporal.refresh_api_key! },
                         logger: ActiveJob::Temporal::Logger,
                         listener_factory: nil)
           sources = []
 
-          if configuration.tls_cert_watch
-            sources << Source.new(name: "tls", paths: tls_paths(configuration), on_change: on_tls_change)
-          end
+          if configuration.credential_watch
+            tls = tls_paths(configuration)
+            sources << Source.new(name: "tls", paths: tls, on_change: on_tls_change) if tls.any?
 
-          if configuration.api_key_watch
-            sources << Source.new(name: "api_key", paths: [configuration.api_key_file], on_change: on_api_key_change)
+            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(

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,8 @@ 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}"
-              requires_path: "requires api_key_file to watch"
 
             credential_poll_interval:
               invalid: "must be a positive number of seconds, got: %{value}"

data/lib/activejob/temporal/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activejob-temporal
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Temporal Technologies