activejob-temporal 0.1.0 → 0.3.0

data/lib/activejob/temporal/payload.rb

@@ -38,7 +38,10 @@ module ActiveJob
     #     job_class: "MyJob",
     #     job_id: "abc-123",
     #     queue_name: "default",
-    #     arguments: [{"_aj_serialized"=>"ActiveJob::Serializers::ObjectSerializer", ...}],
+    #     active_job: {
+    #       "arguments" => [{"_aj_serialized"=>"ActiveJob::Serializers::ObjectSerializer", ...}],
+    #       ...
+    #     },
     #     executions: 0,
     #     exception_executions: {},
     #     scheduled_at: "2025-10-29T12:00:00Z" # optional
@@ -83,7 +86,7 @@ module ActiveJob
       #   - :job_class [String] Fully-qualified job class name
       #   - :job_id [String] Unique job identifier
       #   - :queue_name [String] Target queue name
-      #   - :arguments [Array] Serialized job arguments (via ActiveJob::Arguments)
+      #   - :active_job [Hash] ActiveJob serialized payload, including arguments
       #   - :executions [Integer] Current execution count (default 0)
       #   - :exception_executions [Hash] Exception execution counts (default {})
       #   - :scheduled_at [String] ISO8601 timestamp (optional)
@@ -98,7 +101,7 @@ module ActiveJob
       # @example Basic job payload
       #   job = MyJob.new
       #   payload = Payload.from_job(job)
-      #   # => { job_class: "MyJob", job_id: "...", arguments: [...], ... }
+      #   # => { job_class: "MyJob", job_id: "...", active_job: { "arguments" => [...] }, ... }
       #
       # @example Scheduled job payload
       #   job = MyJob.new
@@ -155,19 +158,25 @@ module ActiveJob
         final_payload = serializer_for(config).dump(payload)
         final_payload[:scheduled_at] = scheduled_timestamp if scheduled_timestamp
         final_payload = encrypt_payload_for_transport(final_payload, encrypt, config, encryption_context)
-        final_payload = offload_payload_for_transport(final_payload, storage_metadata, config) if offload
-        enforce_size!(final_payload, metrics_payload: payload, config: config) if enforce_size
-        final_payload
+        finalize_transport_payload(
+          final_payload,
+          metrics_payload: payload,
+          config: config,
+          offload: offload ? storage_metadata || {} : nil,
+          enforce_size: enforce_size
+        )
       end
 
       # Deserializes job arguments from a payload hash.
       #
-      # Extracts the serialized arguments array from the payload and uses
-      # ActiveJob's built-in deserialization to reconstruct Ruby objects
+      # Extracts the serialized arguments array from ActiveJob's canonical
+      # serialized job data, falling back to legacy top-level arguments, then
+      # uses ActiveJob's built-in deserialization to reconstruct Ruby objects
       # (including GlobalID references to ActiveRecord models).
       #
-      # @param payload [Hash] Payload hash containing serialized arguments
-      # @option payload [Array] :arguments Serialized arguments (required)
+      # @param payload [Hash] Payload hash containing serialized ActiveJob data
+      # @option payload [Hash] :active_job Full ActiveJob serialized payload
+      # @option payload [Array] :arguments Legacy serialized arguments
       #
       # @return [Array] Deserialized arguments array ready for job.perform(*args)
       #
@@ -175,13 +184,13 @@ module ActiveJob
       # @raise [GlobalID::RecordNotFound] if a GlobalID reference points to a deleted record
       #
       # @example Deserialize arguments
-      #   payload = { arguments: [{"_aj_serialized"=>"..."}] }
+      #   payload = { active_job: { "arguments" => [{"_aj_serialized"=>"..."}] } }
       #   args = Payload.deserialize_args(payload)
       #   # => [actual_ruby_object]
       #
       # @example GlobalID deserialization with deleted record
       #   begin
-      #     payload = { arguments: [{"_aj_globalid"=>"gid://app/User/999"}] }
+      #     payload = { active_job: { "arguments" => [{"_aj_globalid"=>"gid://app/User/999"}] } }
       #     args = Payload.deserialize_args(payload)
       #   rescue ActiveRecord::RecordNotFound => e
       #     # Record was deleted between enqueue and execution
@@ -192,7 +201,7 @@ module ActiveJob
       end
 
       def deserialize_payload_args(payload)
-        serialized_args = payload[:arguments] || payload["arguments"]
+        serialized_args = active_job_arguments(payload) || payload[:arguments] || payload["arguments"]
         ActiveJob::Arguments.deserialize(serialized_args)
       rescue ActiveJob::SerializationError, ActiveJob::Temporal::ConfigurationError
         raise
@@ -216,12 +225,13 @@ module ActiveJob
         encrypt_payload_if_configured(payload, config, encryption_context: encryption_context)
       end
 
-      def offload_payload(payload, metadata:, config: ActiveJob::Temporal.config)
+      def offload_payload(payload, metadata:, config: ActiveJob::Temporal.config, byte_size: nil)
         PayloadStorage.offload_if_needed(
           payload,
           config: config,
           metadata: metadata,
-          workflow_control_fields: WORKFLOW_CONTROL_FIELDS
+          workflow_control_fields: WORKFLOW_CONTROL_FIELDS,
+          byte_size: byte_size
         )
       end
 
@@ -229,19 +239,19 @@ module ActiveJob
         PayloadStorage.delete(payload, config: config)
       end
 
-      def enforce_size!(payload, metrics_payload: payload, config: ActiveJob::Temporal.config)
-        json = JSON.generate(payload)
+      def enforce_size!(payload, metrics_payload: payload, config: ActiveJob::Temporal.config, byte_size: nil)
+        bytes = byte_size || JSON.generate(payload).bytesize
         max_size_kb = config.max_payload_size_kb || 250
         size_limit_bytes = max_size_kb * 1024
-        actual_size_kb = json.bytesize / 1024.0
-        usage_ratio = json.bytesize.to_f / size_limit_bytes
+        actual_size_kb = bytes / 1024.0
+        usage_ratio = bytes.to_f / size_limit_bytes
 
         Observability.emit(
           :payload_serialize,
-          Observability.attributes_from_payload(metrics_payload, bytes: json.bytesize)
+          Observability.attributes_from_payload(metrics_payload, bytes: bytes)
         )
         log_payload_size(metrics_payload, actual_size_kb, max_size_kb, usage_ratio)
-        return if json.bytesize <= size_limit_bytes
+        return if bytes <= size_limit_bytes
 
         message = format(
           "Job payload size (%<actual>.1f KB) exceeds maximum allowed size (%<max>d KB). " \
@@ -262,8 +272,18 @@ module ActiveJob
         encrypt_payload(payload, config: config, encryption_context: encryption_context)
       end
 
-      def offload_payload_for_transport(payload, storage_metadata, config)
-        offload_payload(payload, metadata: storage_metadata || {}, config: config)
+      # One JSON pass feeds both the storage threshold check and the size limit check.
+      def finalize_transport_payload(payload, metrics_payload:, config:, offload:, enforce_size:)
+        return payload unless offload || enforce_size
+
+        byte_size = JSON.generate(payload).bytesize
+        if offload
+          offloaded = offload_payload(payload, metadata: offload, config: config, byte_size: byte_size)
+          byte_size = nil unless offloaded.equal?(payload)
+          payload = offloaded
+        end
+        enforce_size!(payload, metrics_payload: metrics_payload, config: config, byte_size: byte_size) if enforce_size
+        payload
       end
 
       def decrypt_transport_payload(payload, config, encryption_context)
@@ -296,12 +316,24 @@ module ActiveJob
         PayloadSerializers.fetch(config.payload_serializer)
       end
 
-      def serializer_for_transport_payload(payload, _config)
+      def serializer_for_transport_payload(payload, config)
         payload_serializer = payload_serializer_name(payload)
         validate_payload_serializer_version!(payload) if payload_serializer_metadata?(payload)
+        validate_payload_serializer_allowed!(payload_serializer, config)
         PayloadSerializers.fetch(payload_serializer)
       end
 
+      # The payload names its own serializer, so an attacker-supplied workflow input could
+      # otherwise select Marshal (arbitrary code execution) regardless of configuration.
+      def validate_payload_serializer_allowed!(payload_serializer, config)
+        return if PayloadSerializers::DATA_ONLY.include?(payload_serializer)
+        return if payload_serializer == PayloadSerializers.normalize_name(config.payload_serializer)
+
+        raise ActiveJob::SerializationError,
+              "Payload serializer #{payload_serializer.inspect} is not permitted by the configured " \
+              "payload_serializer (#{config.payload_serializer.inspect})"
+      end
+
       def payload_serializer_name(payload)
         serializer_name = payload[:payload_serializer] || payload["payload_serializer"]
         return PayloadSerializers::JSON unless serializer_name
@@ -327,6 +359,13 @@ module ActiveJob
         end
       end
 
+      def active_job_arguments(payload)
+        active_job_payload = payload[:active_job] || payload["active_job"]
+        return unless active_job_payload.respond_to?(:[])
+
+        active_job_payload[:arguments] || active_job_payload["arguments"]
+      end
+
       # Serializes job arguments using ActiveJob's built-in serializer.
       # @api private
       def serialize_arguments(arguments)
@@ -352,12 +391,12 @@ module ActiveJob
           job_class: job.class.name,
           job_id: job.job_id,
           queue_name: job.queue_name,
-          arguments: serialize_arguments(job.arguments || []),
           executions: job.executions || 0,
           exception_executions: job.exception_executions || {}
         }
         active_job_payload = serialized_active_job(job)
         payload[:active_job] = active_job_payload if active_job_payload
+        payload[:arguments] = serialize_arguments(job.arguments || []) unless active_job_payload
         payload
       end
 

data/lib/activejob/temporal/payload_encryption.rb

@@ -32,7 +32,15 @@ module ActiveJob
 
       def decrypt(payload, config, context: nil)
         version = payload[:encrypted_payload_version] || payload["encrypted_payload_version"]
-        return decrypt_legacy(payload, config) if version == LEGACY_VERSION
+        if version == LEGACY_VERSION
+          unless config.allow_legacy_encrypted_payloads
+            raise ActiveJob::SerializationError,
+                  "Version 1 encrypted payloads are rejected; set allow_legacy_encrypted_payloads " \
+                  "to accept payloads enqueued before context-bound encryption"
+          end
+
+          return decrypt_legacy(payload, config)
+        end
         return decrypt_v2(payload, config, context) if version == VERSION
 
         raise ActiveJob::SerializationError, "Unsupported encrypted payload version: #{version.inspect}"

data/lib/activejob/temporal/payload_serializers.rb

@@ -15,6 +15,9 @@ module ActiveJob
       MESSAGE_PACK_ALIAS = :msgpack
       MARSHAL = :marshal
       SUPPORTED = [JSON, MESSAGE_PACK, MESSAGE_PACK_ALIAS, MARSHAL].freeze
+      # Serializers that cannot instantiate arbitrary objects, so a payload may select them
+      # even when the configuration names a different serializer.
+      DATA_ONLY = [JSON, MESSAGE_PACK].freeze
 
       def fetch(name)
         case normalize_name(name)

data/lib/activejob/temporal/payload_storage.rb

@@ -16,9 +16,9 @@ module ActiveJob
         payload[:external_payload] == true || payload["external_payload"] == true
       end
 
-      def offload_if_needed(payload, config:, metadata:, workflow_control_fields:)
+      def offload_if_needed(payload, config:, metadata:, workflow_control_fields:, byte_size: nil)
         return payload unless configured?(config)
-        return payload unless payload_exceeds_threshold?(payload, config)
+        return payload unless payload_exceeds_threshold?(payload, config, byte_size)
 
         reference = dump_payload(payload, config, metadata)
         envelope = {
@@ -62,8 +62,8 @@ module ActiveJob
         !config.payload_storage_adapter.nil? && !config.payload_storage_threshold_kb.nil?
       end
 
-      def payload_exceeds_threshold?(payload, config)
-        JSON.generate(payload).bytesize > (config.payload_storage_threshold_kb * 1024)
+      def payload_exceeds_threshold?(payload, config, byte_size = nil)
+        (byte_size || JSON.generate(payload).bytesize) > (config.payload_storage_threshold_kb * 1024)
       end
 
       def dump_payload(payload, config, metadata)

data/lib/activejob/temporal/rails_environment_loader.rb

@@ -129,14 +129,7 @@ module ActiveJob
         return unless Object.const_defined?(:Rails)
 
         rails = Object.const_get(:Rails)
-        return unless rails.respond_to?(:application) && rails.respond_to?(:env)
-
-        environment = rails.env
-        return unless environment.respond_to?(:development?) && environment.respond_to?(:test?)
-        return unless environment.development? || environment.test?
-
-        application = rails.application
-        application.eager_load! if application.respond_to?(:eager_load!)
+        rails.application.eager_load! if rails.env.development? || rails.env.test?
       end
     end
   end

data/lib/activejob/temporal/reload_signal_queue.rb

@@ -2,38 +2,38 @@
 
 module ActiveJob
   module Temporal
+    # Single-slot signal handoff between a trap handler and the reload thread.
+    #
+    # Backed by Thread::Queue because trap context forbids taking a Mutex.
     class ReloadSignalQueue
-      POLL_INTERVAL_SECONDS = 0.05
-
       def initialize
-        @pending_signal = nil
-        @closed = false
+        @queue = Thread::Queue.new
       end
 
+      # Enqueues a reload signal unless one is already pending or the queue is closed.
+      #
+      # @param signal [String] Signal name
+      # @return [String, nil] The signal when enqueued, nil when coalesced or closed
       def push(signal)
-        return if @closed || @pending_signal
+        return nil if @queue.closed? || !@queue.empty?
 
-        @pending_signal = signal
+        @queue << signal
         signal
+      rescue ClosedQueueError
+        nil
       end
 
+      # Blocks until a signal is pending or the queue is closed.
+      #
+      # @return [String, nil] The pending signal, or nil once closed
       def pop
-        loop do
-          return nil if @closed
-
-          if @pending_signal
-            signal = @pending_signal
-            @pending_signal = nil
-            return signal
-          end
-
-          sleep(POLL_INTERVAL_SECONDS)
-        end
+        @queue.pop
       end
 
+      # @return [void]
       def close
-        @closed = true
-        @pending_signal = nil
+        @queue.clear
+        @queue.close
       end
     end
   end

data/lib/activejob/temporal/retry_handler_extractor.rb

@@ -131,18 +131,33 @@ module ActiveJob
         handlers = job_class.rescue_handlers
         return [] unless handlers.respond_to?(:reverse_each)
 
-        signature = rescue_handlers_signature(handlers)
+        cached = cache[job_class]
+        return cached[:entries] if fresh_cache_entry?(cached, handlers)
 
         @cache_mutex.synchronize do
           cached = cache[job_class]
-          return cached[:entries] if cached && cached[:signature] == signature
+          return cached[:entries] if fresh_cache_entry?(cached, handlers)
 
           entries = yield(handlers).map(&:freeze).freeze
-          cache[job_class] = { signature: signature, entries: entries }.freeze
+          cache[job_class] = {
+            handlers: handlers,
+            signature: rescue_handlers_signature(handlers),
+            entries: entries
+          }.freeze
           entries
         end
       end
 
+      # ActiveJob replaces the rescue_handlers array on every declaration, so
+      # identity is a sound (and allocation-free) freshness check; the signature
+      # comparison stays as a fallback for in-place mutation.
+      def fresh_cache_entry?(cached, handlers)
+        return false unless cached
+        return true if cached[:handlers].equal?(handlers)
+
+        cached[:signature] == rescue_handlers_signature(handlers)
+      end
+
       def rescue_handlers_signature(handlers)
         handlers.reverse_each.map do |class_or_name, handler|
           [class_or_name, handler.object_id]

data/lib/activejob/temporal/schedulable.rb

@@ -10,22 +10,20 @@ module ActiveJob
       end
 
       module ClassMethods
-        def schedule(options = nil, **kwargs)
+        def temporal_schedule(options = nil, **kwargs)
+          return @temporal_schedule if options.nil? && kwargs.empty?
+
           schedule_options = normalize_schedule_options(options, kwargs)
           @temporal_schedule = ActiveJob::Temporal::Schedule.new(self, schedule_options)
         end
 
-        def temporal_schedule
-          @temporal_schedule
-        end
-
         def create_temporal_schedule(options = nil, **kwargs)
           if options || kwargs.any?
             schedule_options = merged_schedule_options(normalize_schedule_options(options, kwargs))
             return ActiveJob::Temporal::Schedule.new(self, schedule_options).create
           end
 
-          raise ArgumentError, "No schedule defined for #{name}" unless temporal_schedule
+          raise ArgumentError, "No temporal_schedule defined for #{name}" unless temporal_schedule
 
           temporal_schedule.create
         end
@@ -43,7 +41,7 @@ module ActiveJob
           when Hash
             options.merge(kwargs)
           else
-            raise ArgumentError, "schedule options must be a Hash"
+            raise ArgumentError, "temporal_schedule options must be a Hash"
           end
         end
 

data/lib/activejob/temporal/schedule.rb

@@ -9,7 +9,7 @@ require_relative "job_payload_builder"
 require_relative "logger"
 require_relative "schedule_options"
 require_relative "search_attributes"
-require_relative "workflows/aj_workflow"
+require_relative "workflow_types"
 
 module ActiveJob
   module Temporal
@@ -96,7 +96,7 @@ module ActiveJob
         payload = annotate_scheduled_payload(payload, workflow_id)
 
         Temporalio::Client::Schedule::Action::StartWorkflow.new(
-          Workflows::AjWorkflow,
+          WorkflowTypes::ACTIVE_JOB,
           payload,
           id: workflow_id,
           task_queue: Adapter.resolve_task_queue(job, config: @config),

data/lib/activejob/temporal/signal_query.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 require "temporalio/error"
+require_relative "job_id_validation"
 require_relative "visibility_query"
 require_relative "workflow_id_builder"
 
 module ActiveJob
   module Temporal
     module SignalQuery
-      UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
       JOB_CLASS_NAME_PATTERN = /\A[A-Z]\w*(?:::[A-Z]\w*)*\z/
       HANDLER_NAME_PATTERN = /\A[a-zA-Z_]\w*\z/
       DEFAULT_REJECT_CONDITION = Object.new.freeze
+      WORKFLOW_NOT_FOUND = Object.new.freeze
 
       class << self
         def signal(job_class, job_id, signal_name, *)
@@ -57,33 +58,48 @@ module ActiveJob
           raise ActiveJob::Temporal::TemporalConnectionError,
                 "Failed to update Temporal workflow for job_id #{job_id}: #{e.message}"
         end
+      end
 
+      class << self
         private
 
-        def with_running_workflow_handle(job_class, job_id)
+        def with_running_workflow_handle(job_class, job_id, &)
           client = ActiveJob::Temporal.client
-          default_handle = client.workflow_handle(default_workflow_id(job_class, job_id), run_id: nil)
+          result = yield_schedule_execution_handle(client, job_id, &)
+          return result unless result.equal?(WORKFLOW_NOT_FOUND)
 
-          begin
-            return yield(default_handle)
-          rescue Temporalio::Error::RPCError => e
-            raise unless rpc_not_found?(e)
-          end
+          result = yield_handle(client.workflow_handle(default_workflow_id(job_class, job_id), run_id: nil), &)
+          return result unless result.equal?(WORKFLOW_NOT_FOUND)
 
           workflow_reference = find_running_workflow_reference(client, job_class, job_id)
           raise workflow_not_found(job_id) unless workflow_reference
 
-          fallback_handle = client.workflow_handle(
+          result = yield_handle(workflow_handle(client, workflow_reference), &)
+          raise workflow_not_found(job_id) if result.equal?(WORKFLOW_NOT_FOUND)
+
+          result
+        end
+
+        def yield_schedule_execution_handle(client, job_id, &)
+          workflow_reference = JobIdValidation.schedule_execution_reference(job_id)
+          return WORKFLOW_NOT_FOUND unless workflow_reference
+
+          yield_handle(workflow_handle(client, workflow_reference), &)
+        end
+
+        def yield_handle(handle, &block)
+          block.call(handle)
+        rescue Temporalio::Error::RPCError => e
+          raise unless rpc_not_found?(e)
+
+          WORKFLOW_NOT_FOUND
+        end
+
+        def workflow_handle(client, workflow_reference)
+          client.workflow_handle(
             workflow_reference.fetch(:workflow_id),
             run_id: workflow_reference[:run_id]
           )
-          begin
-            yield(fallback_handle)
-          rescue Temporalio::Error::RPCError => e
-            raise workflow_not_found(job_id) if rpc_not_found?(e)
-
-            raise
-          end
         end
 
         def query_workflow(handle, handler_name, args, reject_condition)
@@ -119,11 +135,7 @@ module ActiveJob
         end
 
         def validate_job_id!(job_id)
-          return if job_id.is_a?(String) && job_id.match?(UUID_REGEX)
-
-          raise ArgumentError,
-                "Invalid job_id format: expected UUID (e.g., '550e8400-e29b-41d4-a716-446655440000'), " \
-                "got: #{job_id.inspect}"
+          JobIdValidation.validate!(job_id)
         end
 
         def normalize_handler_name!(name, handler_type)
@@ -149,11 +161,11 @@ module ActiveJob
         end
 
         def rpc_not_found?(error)
-          error.code == Temporalio::Error::RPCError::Code::NOT_FOUND
+          error.respond_to?(:code) && error.code == Temporalio::Error::RPCError::Code::NOT_FOUND
         end
 
         def rpc_invalid_argument?(error)
-          error.code == Temporalio::Error::RPCError::Code::INVALID_ARGUMENT
+          error.respond_to?(:code) && error.code == Temporalio::Error::RPCError::Code::INVALID_ARGUMENT
         end
       end
     end

data/lib/activejob/temporal/temporal_options.rb

@@ -11,6 +11,21 @@ module ActiveJob
     #     temporal_options start_to_close_timeout: 30.seconds
     #   end
     #
+    # @example ApplicationJob defaults inherited by subclasses
+    #   class ApplicationJob < ActiveJob::Base
+    #     temporal_options start_to_close_timeout: 2.minutes
+    #   end
+    #
+    #   class QuickJob < ApplicationJob
+    #   end
+    #
+    # @example Merge inherited defaults intentionally
+    #   class DataProcessingJob < ApplicationJob
+    #     temporal_options ApplicationJob.temporal_options.merge(
+    #       heartbeat_timeout: 30.seconds
+    #     )
+    #   end
+    #
     # @example Long-running job with heartbeat
     #   class DataProcessingJob < ApplicationJob
     #     temporal_options(
@@ -59,16 +74,26 @@ module ActiveJob
         #
         # @note Timeout values can be specified as either integers (seconds) or
         #   ActiveSupport::Duration objects (e.g., 2.hours, 30.seconds)
+        #
+        # @note Subclasses inherit parent options unless they declare their own.
+        #   A subclass declaration replaces the inherited hash. Use +merge+ to
+        #   keep inherited keys while overriding selected values.
         def temporal_options(options = nil)
           if options
             validate_timeout_keys!(options)
             @temporal_options = normalize_timeout_values(options)
           end
-          @temporal_options || {}
+          @temporal_options || inherited_temporal_options || {}
         end
 
         private
 
+        def inherited_temporal_options
+          return unless superclass.respond_to?(:temporal_options)
+
+          superclass.temporal_options
+        end
+
         # Validates that only recognized timeout keys are provided
         #
         # @param options [Hash] The options hash to validate

data/lib/activejob/temporal/tls_file.rb

@@ -4,42 +4,42 @@ module ActiveJob
   module Temporal
     module TLSFile
       class Error < StandardError; end
+      # Symlinks are resolved before opening, so NOFOLLOW only trips when the
+      # resolved path is swapped for a symlink between resolution and open.
       OPEN_FLAGS = File::RDONLY | (File.const_defined?(:NOFOLLOW) ? File::NOFOLLOW : 0)
-      USES_NOFOLLOW = File.const_defined?(:NOFOLLOW)
 
       module_function
 
+      # @param path [String, nil] path to a TLS file, symlinks allowed
+      # @return [Boolean] true when the path resolves to a readable regular file
       def readable_regular_file?(path)
-        expanded_path = File.expand_path(path)
-        stat = File.lstat(expanded_path)
-        return false if stat.symlink?
+        resolved_path = File.realpath(File.expand_path(path))
 
-        stat.file? && File.readable?(expanded_path)
-      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
+        File.stat(resolved_path).file? && File.readable?(resolved_path)
+      rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES, Errno::ELOOP
         false
       end
 
+      # Reads a TLS file, resolving symlinks first so Kubernetes secret mounts
+      # (path -> ..data/path -> timestamped directory) work.
+      #
+      # @param path [String, nil] path to a TLS file
+      # @return [String, nil] file contents, or nil when path is blank
+      # @raise [Error] when the path does not resolve to a readable regular file
       def read(path)
         return nil if path.nil? || path.to_s.empty?
 
-        expanded_path = File.expand_path(path)
-        reject_symlink!(expanded_path) unless USES_NOFOLLOW
-        File.open(expanded_path, OPEN_FLAGS) do |file|
+        resolved_path = File.realpath(File.expand_path(path))
+        File.open(resolved_path, OPEN_FLAGS) do |file|
           raise Error, "TLS file path must point to a regular file: #{path}" unless file.stat.file?
 
           file.read
         end
       rescue Errno::ELOOP
-        raise Error, "TLS file path must not be a symlink: #{path}"
+        raise Error, "TLS file path could not be resolved: #{path}"
       rescue Errno::ENOENT, Errno::ENOTDIR, Errno::EACCES
         raise Error, "TLS file path is not readable: #{path}"
       end
-
-      def reject_symlink!(path)
-        return unless File.lstat(path).symlink?
-
-        raise Error, "TLS file path must not be a symlink: #{path}"
-      end
     end
   end
 end