activejob-temporal 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9ea3a46138c59ad643942b6de5431013e9679812845aa2df1e465dfd368120c
-  data.tar.gz: 63232ab58e9ae604053cf68751ba803f5a66e5ad416f6762ad5ee74ea7eef4a5
+  metadata.gz: 79166555209f6e6cf73641c9415feac14e6cffad299940c94ebcba0568c3cfdd
+  data.tar.gz: 4e3f843f44c93c4ce383415b32616f7770c407dec314dbf5e305a820e9095480
 SHA512:
-  metadata.gz: 02c60806fecabadd3744ca003ab45a7ef4331c7f48a361bf3045d22f18f2386278b9c47b729f8d8bd4ad7d17605b3526955f0bd0bf4c2e3a75a9639ec4998620
-  data.tar.gz: 4b3a8d2a876fc3874be63c8c400d7a991c4f4a89d3579c56941eff32e1530a6658bdf338570ffa0c5705872618b39044c5c324646d01c4bbf8317f37def25b04
+  metadata.gz: f1dd16daf2739bbefdb568eb08423ca071fdc4ef96cee1b775d1fbb383728abec3c226d4f52d1ee633db6b7048ae5e6d68c0842a72dedf40cb03fdb4fe7d41ca
+  data.tar.gz: 9c17b2bf542f9990b68db645b32edd0176d8250309e70577d583f7d2102ed5cf176000ad5a5384a51c5ac4aa58fd18af161c226f389af413d66a0b00f01c84bd

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-06
+
+### Fixed
+- `api_key_watch` and `tls_cert_watch` now fire on Kubernetes projected and secret volumes: kubelet rotates them atomically by swapping a `..data` symlink into a new timestamped directory, so the watched file's own path never appears in the change events and the previous exact-path filter dropped every rotation. Any change inside a watched file's directory now counts as relevant.
+
+## [0.3.0] - 2026-08-06
+
+### Added
+- Bearer-token authentication: `api_key` (sent as the `Authorization: Bearer` header) and `api_key_file`, read through the same hardened path as TLS files — for example a projected Kubernetes ServiceAccount token. `api_key_watch` watches the token file and applies rotated tokens to the live connection via the new `ActiveJob::Temporal.refresh_api_key!` (no reconnect); enqueue-side processes using a rotating token file should call `refresh_api_key!` on their own schedule. `api_key` is redacted from `Configuration#inspect`. Caution: the Temporal SDK enables TLS when an API key is set and `tls` is nil — set `tls = false` explicitly for plaintext in-cluster servers (see the worker setup guide).
+- Custom activity hosting: `worker_activities` registers additional activity classes (or class names) on the worker — for example activities invoked by workflows owned by another service, where only the activity name and JSON payloads travel over the wire. `worker_activejob_workloads = false` turns off the built-in ActiveJob workflows and activities for activities-only workers. Entries must be `Temporalio::Activity::Definition` subclasses; anything else fails worker startup with a `WorkerRegistrationError`.
+- `graceful_shutdown_period` is passed to the Temporal worker, so a shutting-down worker lets running activities finish before their tasks are cancelled instead of cancelling them immediately.
+- Configuration validation for the new attributes: `api_key_file` must be a readable regular file, `api_key_watch` requires `api_key_file`, disabling `worker_activejob_workloads` requires `worker_activities`, and `graceful_shutdown_period` must be >= 0.
+
+### Changed
+- Allow temporalio 1.5 and 1.6 (dependency constraint is now `>= 1.4.0, < 1.7`); both added to the SDK contract-test matrix. Note for consumers upgrading within the range: temporalio 1.6 enables gzip gRPC transport compression by default — opt out with `grpc_compression` if an intermediary cannot handle it.
+
 ## [0.2.0] - 2026-08-06
 
 ### Security

data/activejob-temporal.gemspec

@@ -37,7 +37,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "activemodel", ">= 7.2", "< 9"
   spec.add_dependency "concurrent-ruby", "~> 1.1"
   spec.add_dependency "globalid", ">= 0.3"
-  spec.add_dependency "temporalio", ">= 1.4.0", "< 1.5"
+  spec.add_dependency "temporalio", ">= 1.4.0", "< 1.7"
 
   spec.add_development_dependency "benchmark-ips", "~> 2.14"
   spec.add_development_dependency "github_changelog_generator", "~> 1.18"

data/bin/temporal-worker

@@ -183,23 +183,24 @@ worker_health = ActiveJob::Temporal::WorkerHealth.new(
   max_concurrent_workflows: max_concurrent_workflows
 )
 
+begin
+  registrations = ActiveJob::Temporal::WorkerRegistrations.resolve(config)
+rescue ActiveJob::Temporal::WorkerRegistrationError => e
+  warn "Error: #{e.message}"
+  exit(1)
+end
+
 worker = Temporalio::Worker.new(
   client: client,
   task_queue: task_queue,
-  workflows: [
-    ActiveJob::Temporal::Workflows::AjWorkflow,
-    ActiveJob::Temporal::Workflows::DeadLetterWorkflow
-  ],
-  activities: [
-    ActiveJob::Temporal::Activities::RateLimitActivity,
-    ActiveJob::Temporal::Activities::DependencyStatusActivity,
-    ActiveJob::Temporal::Activities::AjRunnerActivity
-  ],
+  workflows: registrations.workflows,
+  activities: registrations.activities,
   tuner: Temporalio::Worker::Tuner.create_fixed(
     workflow_slots: max_concurrent_workflows,
     activity_slots: max_concurrent_activities,
     local_activity_slots: max_concurrent_activities
   ),
+  graceful_shutdown_period: config.graceful_shutdown_period,
   interceptors: [worker_health]
 )
 
@@ -268,6 +269,17 @@ if config.tls_cert_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
+
 begin
   worker_health.mark_started!
   Temporalio::Worker.run_all(
@@ -279,6 +291,7 @@ rescue Interrupt
 ensure
   worker_health.mark_stopped!
   certificate_watcher&.stop
+  api_key_watcher&.stop
   reload_signal_queue.close
   reload_signal_thread.join(1)
   health_check_server&.stop

data/lib/activejob/temporal/certificate_watcher.rb

@@ -89,9 +89,14 @@ module ActiveJob
         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|
-          @paths.include?(File.expand_path(path))
+          expanded = File.expand_path(path)
+          @paths.include?(expanded) || directories.any? { |dir| expanded.start_with?("#{dir}/") }
         end
       end
 

data/lib/activejob/temporal/client.rb

@@ -116,16 +116,33 @@ module ActiveJob
               )
       end
 
-      # Builds connection keyword arguments (including TLS options).
+      # Builds connection keyword arguments (TLS options and API key).
       # @api private
       def connection_kwargs(configuration)
+        kwargs = {}
+
         tls = tls_options(configuration)
-        return {} if tls.nil?
+        kwargs[:tls] = tls unless tls.nil?
+
+        api_key = resolve_api_key(configuration)
+        kwargs[:api_key] = api_key if api_key
 
-        { tls: tls }
+        kwargs
       end
       private_class_method :connection_kwargs
 
+      # 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.
+      # @api private
+      def resolve_api_key(configuration)
+        inline = configuration.api_key if configuration.respond_to?(:api_key)
+        return inline unless inline.nil? || inline.to_s.strip.empty?
+
+        path = configuration.api_key_file if configuration.respond_to?(:api_key_file)
+        read_tls_file(path)&.strip.presence
+      end
+
       # Extracts TLS options from config or environment variables.
       # @api private
       def tls_options(configuration)

data/lib/activejob/temporal/configuration.rb

@@ -136,6 +136,29 @@ module ActiveJob
         description: "Signal used by workers to reload TLS certificates manually"
       },
 
+      api_key: {
+        default: nil,
+        env_var: "ACTIVEJOB_TEMPORAL_API_KEY",
+        type: :string,
+        description: "Optional API key sent as the Authorization bearer token"
+      },
+
+      api_key_file: {
+        default: nil,
+        env_var: "ACTIVEJOB_TEMPORAL_API_KEY_FILE",
+        type: :string,
+        description: "Optional file read for the API key when the client is built, for example a " \
+                     "projected Kubernetes ServiceAccount token. An explicit api_key takes precedence"
+      },
+
+      api_key_watch: {
+        default: false,
+        env_var: "ACTIVEJOB_TEMPORAL_API_KEY_WATCH",
+        type: :boolean,
+        description: "Watch api_key_file and refresh the token when it changes (kubelet rotates " \
+                     "projected tokens atomically, long before they expire)"
+      },
+
       priority_task_queues: {
         default: -> { {} },
         type: :hash,
@@ -385,6 +408,29 @@ module ActiveJob
         env_var: "ACTIVEJOB_TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS",
         type: :integer,
         description: "Maximum concurrent workflow tasks per worker"
+      },
+
+      worker_activities: {
+        default: -> { [] },
+        type: :array,
+        description: "Additional activity classes (or class names) the worker registers, for example " \
+                     "activities invoked by workflows owned by another service"
+      },
+
+      worker_activejob_workloads: {
+        default: true,
+        env_var: "ACTIVEJOB_TEMPORAL_WORKER_ACTIVEJOB_WORKLOADS",
+        type: :boolean,
+        description: "Register the built-in ActiveJob workflows and activities on the worker. Disable " \
+                     "for workers that only host worker_activities"
+      },
+
+      graceful_shutdown_period: {
+        default: 0.0,
+        env_var: "ACTIVEJOB_TEMPORAL_GRACEFUL_SHUTDOWN_PERIOD",
+        type: :float,
+        description: "Seconds a shutting-down worker lets running activities finish before their " \
+                     "tasks are cancelled (0 cancels immediately, matching the SDK default)"
       }
     }.freeze
 
@@ -457,7 +503,7 @@ module ActiveJob
       end
 
       # Attributes holding secrets, redacted by {#inspect}.
-      REDACTED_ATTRIBUTES = %i[encryption_key encryption_old_keys tls].freeze
+      REDACTED_ATTRIBUTES = %i[encryption_key encryption_old_keys tls api_key].freeze
       REDACTED_PLACEHOLDER = "[FILTERED]"
 
       # Returns the configuration with secret attributes redacted.
@@ -661,6 +707,13 @@ module ActiveJob
                   allow_nil: false
                 }
 
+      validates :graceful_shutdown_period,
+                numericality: {
+                  greater_than_or_equal_to: 0,
+                  message: :graceful_shutdown_period_negative,
+                  allow_nil: false
+                }
+
       validates :continue_as_new_history_event_threshold,
                 numericality: {
                   greater_than: 0,
@@ -698,6 +751,8 @@ module ActiveJob
       validate :validate_encryption_settings
       validate :validate_payload_storage_settings
       validate :validate_tls_settings
+      validate :validate_api_key_settings
+      validate :validate_worker_registration_settings
       validate :validate_local_activity_helpers
       validate :validate_dependency_wait_settings
 
@@ -1024,6 +1079,30 @@ module ActiveJob
         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_worker_registration_settings
+        unless [true, false].include?(worker_activejob_workloads)
+          errors.add(:worker_activejob_workloads, :not_boolean, value: worker_activejob_workloads.inspect)
+          return
+        end
+
+        return if worker_activejob_workloads || Array(worker_activities).any?
+
+        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)

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

@@ -136,3 +136,18 @@ en:
             tls_reload_signal:
               blank: "must be present when configured"
               invalid: "must be a signal name like HUP or USR1, got: %{value}"
+
+            api_key_file:
+              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:
+              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}"
+              requires_activities: "requires worker_activities when disabled - the worker would have nothing to register"
+
+            graceful_shutdown_period:
+              graceful_shutdown_period_negative: "must be >= 0 seconds, got: %{value}"

data/lib/activejob/temporal/version.rb

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

data/lib/activejob/temporal/worker_registrations.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "temporalio/activity"
+
+module ActiveJob
+  module Temporal
+    # Resolves which workflows and activities a worker registers, from configuration.
+    #
+    # By default a worker hosts the built-in ActiveJob workloads. `worker_activities`
+    # adds custom activity classes - for example activities invoked by workflows owned
+    # by another service, where only the activity name and JSON payloads travel over
+    # the wire. Setting `worker_activejob_workloads = false` turns the worker into an
+    # activities-only worker that hosts nothing but those custom activities.
+    module WorkerRegistrations
+      Result = Struct.new(:workflows, :activities, keyword_init: true)
+
+      class << self
+        # Configuration validation rejects the nothing-to-register combination up front
+        # (see Configuration#validate_worker_registration_settings).
+        #
+        # @param configuration [ActiveJob::Temporal::Configuration]
+        # @return [Result] workflows and activities to pass to Temporalio::Worker
+        # @raise [WorkerRegistrationError] when a worker_activities entry does not resolve
+        #   to a Temporalio::Activity::Definition subclass
+        def resolve(configuration)
+          workflows = []
+          activities = custom_activities(configuration)
+
+          if configuration.worker_activejob_workloads
+            workflows += [
+              Workflows::AjWorkflow,
+              Workflows::DeadLetterWorkflow
+            ]
+            activities += [
+              Activities::RateLimitActivity,
+              Activities::DependencyStatusActivity,
+              Activities::AjRunnerActivity
+            ]
+          end
+
+          Result.new(workflows: workflows, activities: activities)
+        end
+
+        private
+
+        def custom_activities(configuration)
+          Array(configuration.worker_activities).map { |entry| resolve_activity(entry) }
+        end
+
+        def resolve_activity(entry)
+          activity = entry.is_a?(String) ? constantize_activity(entry) : entry
+          return activity if activity.is_a?(Class) && activity < Temporalio::Activity::Definition
+
+          raise WorkerRegistrationError,
+                "worker_activities entry #{entry.inspect} is not a Temporalio::Activity::Definition subclass"
+        end
+
+        def constantize_activity(name)
+          name.constantize
+        rescue NameError
+          raise WorkerRegistrationError, "worker_activities entry #{name.inspect} does not resolve to a class"
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/worker_runtime.rb

@@ -14,3 +14,4 @@ require_relative "workflows/dead_letter_workflow"
 require_relative "activities/rate_limit_activity"
 require_relative "activities/dependency_status_activity"
 require_relative "activities/aj_runner_activity"
+require_relative "worker_registrations"

data/lib/activejob/temporal.rb

@@ -99,6 +99,11 @@ module ActiveJob
     # @see Cancel.cancel
     class TemporalConnectionError < Error; end
 
+    # Raised when a worker_activities entry cannot be used as a Temporal activity.
+    #
+    # @see WorkerRegistrations.resolve
+    class WorkerRegistrationError < Error; end
+
     extend Configurable
 
     class << self
@@ -157,6 +162,20 @@ module ActiveJob
         fresh_client
       end
 
+      # Re-reads the API key (api_key or api_key_file) and applies it to the memoized
+      # client's live connection. No reconnect happens - the SDK sends the header per-RPC
+      # from the connection's stored options. Worker processes call this from the
+      # api_key_watch file watcher; a long-lived enqueue-side process using a rotating
+      # token file must call it on its own schedule (nothing watches the file there).
+      #
+      # @return [String, nil] the freshly resolved API key
+      def refresh_api_key!
+        fresh_key = Client.resolve_api_key(config)
+        client.connection.api_key = fresh_key
+        Logger.log_event("api_key_refreshed")
+        fresh_key
+      end
+
       # Cancels a running or scheduled job by job ID.
       #
       # This method requests cancellation for the Temporal workflow associated with the job.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activejob-temporal
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Temporal Technologies
@@ -87,7 +87,7 @@ dependencies:
         version: 1.4.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -97,7 +97,7 @@ dependencies:
         version: 1.4.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.5'
+        version: '1.7'
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
@@ -371,6 +371,7 @@ files:
 - lib/activejob/temporal/worker_client_reloader.rb
 - lib/activejob/temporal/worker_health.rb
 - lib/activejob/temporal/worker_pool.rb
+- lib/activejob/temporal/worker_registrations.rb
 - lib/activejob/temporal/worker_runtime.rb
 - lib/activejob/temporal/workflow_enqueuer.rb
 - lib/activejob/temporal/workflow_enqueuer_batch.rb