activejob-temporal 0.1.0

data/lib/activejob/temporal/payload_serializers/marshal.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module ActiveJob
+  module Temporal
+    module PayloadSerializers
+      module Marshal
+        extend self
+
+        NAME = "marshal"
+
+        def dump(payload)
+          envelope(Base64.strict_encode64(::Marshal.dump(payload)))
+        end
+
+        def load(payload)
+          # Marshal support is opt-in and only safe for trusted Temporal histories.
+          # rubocop:disable Security/MarshalLoad
+          normalize_top_level_keys(::Marshal.load(serialized_data(payload)))
+          # rubocop:enable Security/MarshalLoad
+        rescue StandardError => e
+          raise ActiveJob::SerializationError, "Unable to deserialize Marshal payload: #{e.message}"
+        end
+
+        def envelope?(payload)
+          (payload[:payload_serializer] || payload["payload_serializer"]) == NAME
+        end
+
+        private
+
+        def envelope(serialized_data)
+          {
+            serialized_payload: true,
+            payload_serializer: NAME,
+            payload_serializer_version: PayloadSerializers::ENVELOPE_VERSION,
+            serialized_data: serialized_data
+          }
+        end
+
+        def serialized_data(payload)
+          Base64.strict_decode64(payload[:serialized_data] || payload["serialized_data"])
+        end
+
+        def normalize_top_level_keys(payload)
+          payload.each_with_object({}) do |(key, value), normalized|
+            normalized[key.to_sym] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/payload_serializers/message_pack.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module ActiveJob
+  module Temporal
+    module PayloadSerializers
+      module MessagePack
+        extend self
+
+        NAME = "message_pack"
+
+        def dump(payload)
+          envelope(Base64.strict_encode64(message_pack.pack(payload)))
+        end
+
+        def load(payload)
+          normalize_top_level_keys(message_pack.unpack(serialized_data(payload)))
+        rescue StandardError => e
+          raise if e.is_a?(ConfigurationError)
+
+          raise ActiveJob::SerializationError, "Unable to deserialize MessagePack payload: #{e.message}"
+        end
+
+        def envelope?(payload)
+          (payload[:payload_serializer] || payload["payload_serializer"]) == NAME
+        end
+
+        private
+
+        def envelope(serialized_data)
+          {
+            serialized_payload: true,
+            payload_serializer: NAME,
+            payload_serializer_version: PayloadSerializers::ENVELOPE_VERSION,
+            serialized_data: serialized_data
+          }
+        end
+
+        def serialized_data(payload)
+          Base64.strict_decode64(payload[:serialized_data] || payload["serialized_data"])
+        end
+
+        def message_pack
+          require "msgpack"
+          ::MessagePack
+        rescue LoadError
+          raise ConfigurationError, 'MessagePack payload serialization requires applications to add gem "msgpack"'
+        end
+
+        def normalize_top_level_keys(payload)
+          payload.each_with_object({}) do |(key, value), normalized|
+            normalized[key.to_sym] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activejob/temporal/payload_serializers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "payload_serializers/json"
+require_relative "payload_serializers/marshal"
+require_relative "payload_serializers/message_pack"
+
+module ActiveJob
+  module Temporal
+    module PayloadSerializers
+      module_function
+
+      ENVELOPE_VERSION = 1
+      JSON = :json
+      MESSAGE_PACK = :message_pack
+      MESSAGE_PACK_ALIAS = :msgpack
+      MARSHAL = :marshal
+      SUPPORTED = [JSON, MESSAGE_PACK, MESSAGE_PACK_ALIAS, MARSHAL].freeze
+
+      def fetch(name)
+        case normalize_name(name)
+        when JSON then PayloadSerializers::Json
+        when MESSAGE_PACK then PayloadSerializers::MessagePack
+        when MARSHAL then PayloadSerializers::Marshal
+        else
+          raise ConfigurationError, "Unsupported payload serializer: #{name.inspect}"
+        end
+      end
+
+      def normalize_name(name)
+        normalized = name.to_sym
+        normalized == MESSAGE_PACK_ALIAS ? MESSAGE_PACK : normalized
+      rescue NoMethodError
+        name
+      end
+    end
+  end
+end

data/lib/activejob/temporal/payload_storage.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "logger"
+
+module ActiveJob
+  module Temporal
+    module PayloadStorage
+      extend self
+
+      VERSION = 1
+      REFERENCE_KEY = :external_payload_reference
+
+      def external?(payload)
+        payload[:external_payload] == true || payload["external_payload"] == true
+      end
+
+      def offload_if_needed(payload, config:, metadata:, workflow_control_fields:)
+        return payload unless configured?(config)
+        return payload unless payload_exceeds_threshold?(payload, config)
+
+        reference = dump_payload(payload, config, metadata)
+        envelope = {
+          external_payload: true,
+          external_payload_version: VERSION,
+          REFERENCE_KEY => reference
+        }
+        preserve_workflow_control_fields(payload, envelope, workflow_control_fields)
+      end
+
+      def load(payload, config:, workflow_control_fields:)
+        return payload unless external?(payload)
+
+        version = payload[:external_payload_version] || payload["external_payload_version"]
+        unless version == VERSION
+          raise ActiveJob::SerializationError, "Unsupported external payload version: #{version.inspect}"
+        end
+
+        loaded_payload = load_payload(payload, config)
+        preserve_workflow_control_fields(payload, loaded_payload, workflow_control_fields)
+      end
+
+      def delete(payload, config:)
+        return unless external?(payload)
+
+        adapter = storage_adapter(config)
+        return unless adapter.respond_to?(:delete)
+
+        adapter.delete(payload_reference(payload))
+      rescue StandardError => e
+        ActiveJob::Temporal::Logger.warn(
+          "payload_storage_delete_failed",
+          error_class: e.class.name,
+          error_message: e.message
+        )
+      end
+
+      private
+
+      def configured?(config)
+        !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)
+      end
+
+      def dump_payload(payload, config, metadata)
+        storage_adapter(config).dump(payload, metadata: metadata.compact)
+      rescue ActiveJob::SerializationError
+        raise
+      rescue StandardError => e
+        raise ActiveJob::SerializationError, "Unable to store external payload: #{e.message}"
+      end
+
+      def load_payload(payload, config)
+        loaded_payload = storage_adapter(config).load(payload_reference(payload))
+        return loaded_payload if loaded_payload.is_a?(Hash)
+
+        raise ActiveJob::SerializationError, "External payload adapter returned #{loaded_payload.class}, expected Hash"
+      end
+
+      def storage_adapter(config)
+        config.payload_storage_adapter ||
+          raise(ActiveJob::SerializationError, "External payload requires payload_storage_adapter")
+      end
+
+      def payload_reference(payload)
+        payload[REFERENCE_KEY] || payload[REFERENCE_KEY.to_s]
+      end
+
+      def preserve_workflow_control_fields(source_payload, target_payload, workflow_control_fields)
+        workflow_control_fields.each do |key|
+          value = source_payload[key] || source_payload[key.to_s]
+          target_payload[key] = value if value
+        end
+
+        target_payload
+      end
+    end
+  end
+end

data/lib/activejob/temporal/rails_environment_loader.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module Temporal
+    module RailsEnvironmentLoader
+      class Error < StandardError; end
+
+      Result = Struct.new(:loaded, :rails_root, :environment_path, :warnings, keyword_init: true) do
+        def loaded?
+          loaded
+        end
+      end
+
+      UNSAFE_WRITE_BITS = 0o022
+
+      module_function
+
+      def load!(rails_root:, warning_io: $stderr, require_environment: Kernel.method(:require))
+        result = resolve(rails_root)
+        result.warnings.each { |warning| warning_io.puts(warning) }
+        return result unless result.loaded?
+
+        require_environment.call(result.environment_path)
+        eager_load_rails_application
+        result
+      end
+
+      def resolve(rails_root)
+        explicit_root = rails_root != "."
+        expanded_root = File.expand_path(rails_root)
+        return missing_root_result(expanded_root, explicit_root) unless File.directory?(expanded_root)
+
+        resolve_existing_root(rails_root, explicit_root, File.realpath(expanded_root))
+      rescue Errno::EACCES => e
+        raise Error, "Cannot inspect Rails application at: #{expanded_root} (#{e.message})"
+      end
+
+      def resolve_existing_root(rails_root, explicit_root, canonical_root)
+        paths = rails_paths(canonical_root)
+        return non_rails_result(canonical_root, rails_root, explicit_root) unless File.file?(paths.fetch(:application))
+
+        environment_path = paths.fetch(:environment)
+        raise Error, "Cannot find Rails environment at: #{environment_path}" unless File.file?(environment_path)
+
+        canonical_paths = canonicalize_paths(
+          canonical_root,
+          paths.fetch(:config),
+          paths.fetch(:application),
+          environment_path
+        )
+        validate_paths_stay_under_root!(canonical_root, canonical_paths)
+        validate_paths_not_writable_by_group_or_world!(canonical_paths)
+
+        Result.new(
+          loaded: true,
+          rails_root: canonical_root,
+          environment_path: canonical_paths.fetch(environment_path),
+          warnings: owner_warnings(canonical_paths.values)
+        )
+      end
+
+      def rails_paths(canonical_root)
+        config_path = File.join(canonical_root, "config")
+        {
+          config: config_path,
+          application: File.join(config_path, "application.rb"),
+          environment: File.join(config_path, "environment.rb")
+        }
+      end
+
+      def missing_root_result(expanded_root, explicit_root)
+        raise Error, "Cannot find Rails application at: #{expanded_root}" if explicit_root
+
+        Result.new(loaded: false, rails_root: expanded_root, environment_path: nil, warnings: [])
+      end
+
+      def non_rails_result(canonical_root, rails_root, explicit_root)
+        warnings = explicit_root ? non_rails_warnings(rails_root) : []
+        Result.new(loaded: false, rails_root: canonical_root, environment_path: nil, warnings: warnings)
+      end
+
+      def canonicalize_paths(*paths)
+        paths.to_h { |path| [path, File.realpath(path)] }
+      end
+
+      def validate_paths_stay_under_root!(canonical_root, canonical_paths)
+        escaped_path = canonical_paths.values.find { |path| !path_under_root?(canonical_root, path) }
+        return unless escaped_path
+
+        raise Error, "Refusing to load Rails environment path outside RAILS_ROOT: #{escaped_path}"
+      end
+
+      def validate_paths_not_writable_by_group_or_world!(paths)
+        unsafe_path = paths.values.find { |path| group_or_world_writable?(path) }
+        return unless unsafe_path
+
+        raise Error, "refusing to load Rails environment from group- or world-writable path: #{unsafe_path}"
+      end
+
+      def path_under_root?(canonical_root, path)
+        path == canonical_root || path.start_with?("#{canonical_root}#{File::SEPARATOR}")
+      end
+
+      def group_or_world_writable?(path)
+        File.stat(path).mode.anybits?(UNSAFE_WRITE_BITS)
+      end
+
+      def owner_warnings(paths)
+        current_uid = Process.uid
+        unsafe_owner_path = paths.find do |path|
+          owner_uid = File.stat(path).uid
+          owner_uid != current_uid && !owner_uid.zero?
+        end
+        return [] unless unsafe_owner_path
+
+        [
+          "Warning: Rails environment path is not owned by the current user or root: #{unsafe_owner_path}"
+        ]
+      end
+
+      def non_rails_warnings(rails_root)
+        [
+          "Warning: #{rails_root} does not appear to be a Rails application",
+          "Continuing without Rails environment. Job classes may not be available."
+        ]
+      end
+
+      def eager_load_rails_application
+        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!)
+      end
+    end
+  end
+end

data/lib/activejob/temporal/rate_limit_options.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "active_support/concern"
+require "active_support/core_ext/numeric/time"
+
+module ActiveJob
+  module Temporal
+    # Provides per-job rate limit metadata via the +rate_limit+ class method.
+    module RateLimitOptions
+      extend ActiveSupport::Concern
+
+      PERIOD_SECONDS = {
+        second: 1.0,
+        minute: 60.0,
+        hour: 3600.0
+      }.freeze
+
+      def self.normalize(limit, per:, key: nil)
+        normalized_limit = normalize_limit(limit)
+        normalized_interval = normalize_interval(per)
+        normalized = { limit: normalized_limit, interval: normalized_interval }
+        normalized[:key] = normalize_key(key) if key
+        normalized
+      end
+
+      def self.normalize_hash(value)
+        raise ArgumentError, "rate limit must be a Hash" unless value.is_a?(Hash)
+
+        limit = value[:limit] || value["limit"]
+        interval = value[:interval] || value["interval"]
+        per = value[:per] || value["per"] || interval
+        key = value[:key] || value["key"]
+
+        normalize(limit, per: per, key: key)
+      end
+
+      def self.normalize_limit(limit)
+        raise ArgumentError, "rate limit must be a positive integer" unless limit.is_a?(Integer) && limit.positive?
+
+        limit
+      end
+      private_class_method :normalize_limit
+
+      def self.normalize_interval(value)
+        interval = case value
+                   when Symbol
+                     PERIOD_SECONDS.fetch(value) { raise ArgumentError, "unsupported rate limit period: #{value}" }
+                   when ActiveSupport::Duration, Numeric
+                     value.to_f
+                   else
+                     raise ArgumentError, "rate limit period must be a Symbol, Numeric, or ActiveSupport::Duration"
+                   end
+
+        unless interval.finite? && interval.positive?
+          raise ArgumentError, "rate limit period must be finite and positive"
+        end
+
+        interval
+      end
+      private_class_method :normalize_interval
+
+      def self.normalize_key(key)
+        normalized_key = key.to_s.strip
+        raise ArgumentError, "rate limit key must be present" if normalized_key.empty?
+
+        normalized_key
+      end
+      private_class_method :normalize_key
+
+      class_methods do
+        def rate_limit(limit = nil, per: nil, key: nil)
+          if limit
+            raise ArgumentError, "rate limit period is required" if per.nil?
+
+            @rate_limit_options = RateLimitOptions.normalize(limit, per: per, key: key)
+          end
+
+          @rate_limit_options || inherited_rate_limit_options || {}
+        end
+
+        private
+
+        def inherited_rate_limit_options
+          return unless superclass.respond_to?(:rate_limit)
+
+          superclass.rate_limit
+        end
+      end
+    end
+  end
+end
+
+ActiveJob::Base.include(ActiveJob::Temporal::RateLimitOptions) if defined?(ActiveJob::Base)

data/lib/activejob/temporal/rate_limiters/memory.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+require_relative "../rate_limit_options"
+
+module ActiveJob
+  module Temporal
+    module RateLimiters
+      class MemoryBucketStore
+        Bucket = Struct.new(:timestamps, :mutex, :last_touched_at, :references)
+        SWEEP_INTERVAL = 1.0
+
+        def initialize
+          @buckets_by_key = Concurrent::Map.new
+          @buckets_mutex = Mutex.new
+          @next_sweep_at = nil
+        end
+
+        def acquire(keys, now)
+          @buckets_mutex.synchronize do
+            keys.uniq.sort.map do |key|
+              bucket = bucket_for(key, now)
+              bucket.references += 1
+              [key, bucket]
+            end
+          end
+        end
+
+        def release(bucket_entries, now)
+          @buckets_mutex.synchronize do
+            bucket_entries.each do |key, bucket|
+              bucket.references -= 1
+              @buckets_by_key.delete_pair(key, bucket) if evictable_bucket?(key, bucket, now)
+            end
+          end
+        end
+
+        def synchronize(bucket_entries, &)
+          synchronize_buckets(bucket_entries.map(&:last), &)
+        end
+
+        def touch(bucket_entries, now)
+          bucket_entries.each do |entry|
+            bucket = entry.fetch(1)
+            bucket.last_touched_at = now unless bucket.timestamps.empty?
+          end
+        end
+
+        def prune_expired_timestamps(bucket, interval, now)
+          cutoff = now - interval
+          timestamps = bucket.timestamps
+          timestamps.shift while timestamps.first && timestamps.first <= cutoff
+          timestamps
+        end
+
+        def sweep_if_due(now)
+          return unless sweep_due?(now)
+
+          bucket_entries = acquire_sweep_bucket_entries
+          synchronize(bucket_entries) do
+            bucket_entries.each do |key, bucket|
+              prune_expired_timestamps(bucket, key.fetch(1), now)
+            end
+          end
+        ensure
+          release(bucket_entries, now) if bucket_entries
+        end
+
+        private
+
+        def bucket_for(key, now)
+          @buckets_by_key.compute_if_absent(key) { Bucket.new([], Mutex.new, now, 0) }
+        end
+
+        def sweep_due?(now)
+          @buckets_mutex.synchronize do
+            return false if @next_sweep_at && now < @next_sweep_at
+
+            @next_sweep_at = now + SWEEP_INTERVAL
+            true
+          end
+        end
+
+        def acquire_sweep_bucket_entries
+          @buckets_mutex.synchronize do
+            @buckets_by_key.each_pair
+                           .to_a
+                           .sort_by(&:first)
+                           .each_with_object([]) do |(key, bucket), bucket_entries|
+              next unless bucket.references.zero?
+
+              bucket.references += 1
+              bucket_entries << [key, bucket]
+            end
+          end
+        end
+
+        def evictable_bucket?(key, bucket, now)
+          bucket.references.zero? &&
+            bucket.timestamps.empty? &&
+            now - bucket.last_touched_at >= key.fetch(1)
+        end
+
+        def synchronize_buckets(buckets, index = 0, &)
+          return yield if index == buckets.length
+
+          buckets[index].mutex.synchronize do
+            synchronize_buckets(buckets, index + 1, &)
+          end
+        end
+      end
+
+      # Process-local sliding-window limiter for development, tests, and single-worker setups.
+      class Memory
+        def initialize(clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @clock = clock
+          @bucket_store = MemoryBucketStore.new
+        end
+
+        def wait_time_for(rate_limits)
+          limits = normalize_rate_limits(rate_limits)
+          return 0.0 if limits.empty?
+
+          now = @clock.call.to_f
+          with_bucket_entries(limits, now) do |bucket_entries|
+            wait_time_for_limits(limits, now, bucket_entries)
+          end
+        end
+
+        private
+
+        def normalize_rate_limits(rate_limits)
+          Array(rate_limits).map { |rate_limit| normalize_rate_limit(rate_limit) }
+        end
+
+        def normalize_rate_limit(rate_limit)
+          normalized = RateLimitOptions.normalize_hash(rate_limit)
+          key = normalized[:key].to_s.strip
+          raise ArgumentError, "rate limit key must be present" if key.empty?
+
+          normalized.merge(key: key)
+        end
+
+        def wait_time_for_limit(rate_limit, now, bucket)
+          timestamps = active_timestamps(rate_limit, now, bucket)
+          return 0.0 if timestamps.length < rate_limit[:limit]
+
+          [timestamps.first + rate_limit[:interval] - now, 0.0].max
+        end
+
+        def record(rate_limit, now, bucket)
+          active_timestamps(rate_limit, now, bucket) << now
+        end
+
+        def record_limits(limits, now, bucket_entries_by_key)
+          limits.uniq { |rate_limit| bucket_key(rate_limit) }.each do |rate_limit|
+            record(rate_limit, now, bucket_entries_by_key.fetch(bucket_key(rate_limit)))
+          end
+        end
+
+        def active_timestamps(rate_limit, now, bucket)
+          @bucket_store.prune_expired_timestamps(bucket, rate_limit[:interval], now)
+        end
+
+        def bucket_key(rate_limit)
+          [rate_limit[:key], rate_limit[:interval]].freeze
+        end
+
+        def bucket_keys_for(limits)
+          limits.map { |rate_limit| bucket_key(rate_limit) }
+        end
+
+        def with_bucket_entries(limits, now)
+          bucket_entries = @bucket_store.acquire(bucket_keys_for(limits), now)
+          @bucket_store.synchronize(bucket_entries) do
+            yield bucket_entries
+          end
+        ensure
+          if bucket_entries
+            @bucket_store.release(bucket_entries, now)
+            @bucket_store.sweep_if_due(now)
+          end
+        end
+
+        def wait_time_for_limits(limits, now, bucket_entries)
+          bucket_entries_by_key = bucket_entries.to_h
+          wait_time = limits.map do |rate_limit|
+            wait_time_for_limit(rate_limit, now, bucket_entries_by_key.fetch(bucket_key(rate_limit)))
+          end.max || 0.0
+          record_limits(limits, now, bucket_entries_by_key) unless wait_time.positive?
+          @bucket_store.touch(bucket_entries, now)
+          wait_time
+        end
+      end
+    end
+  end
+end