hatchet-sdk 0.2.0 → 0.3.0

data/lib/hatchet/durable_context.rb

@@ -23,53 +23,123 @@ module Hatchet
   #     result = ctx.wait_for("event", Hatchet::UserEventCondition.new(event_key: "user:update"))
   #   end
   class DurableContext < Context
+    # @return [Hatchet::WorkerRuntime::DurableEviction::DurableEvictionManager, nil]
+    attr_accessor :eviction_manager
+
+    # @return [String, nil] The action key used by the eviction manager to
+    #   identify this run invocation.
+    attr_accessor :action_key
+
+    # @return [Hatchet::WorkerRuntime::DurableEventListener, nil] New-style bidi
+    #   listener. When set the context delegates through it instead of the
+    #   legacy RegisterDurableEvent/ListenForDurableEvent path.
+    attr_accessor :durable_event_listener
+
+    # @return [Integer] Durable-task invocation count (>= 1).
+    attr_accessor :invocation_count
+
+    # @return [String, nil] Engine version string advertised via GetVersion.
+    attr_accessor :engine_version
+
     # Sleep for a specified duration. The task is suspended and resumed
     # by the engine after the duration expires.
     #
+    # Delegates to {#wait_for} with a {Hatchet::SleepCondition} so that both
+    # sleeps and event waits share a single registration / eviction path.
+    #
     # @param duration [Integer, String] Duration in seconds, or a duration string (e.g. "60s")
+    # @param label [String, nil] Optional wait label shown in durable event logs.
     # @return [Hash, nil] Result from the sleep event
-    def sleep_for(duration:)
-      signal_key = "sleep_#{duration}"
-
+    def sleep_for(duration:, label: nil)
       duration_str = duration.is_a?(String) ? duration : "#{duration}s"
+      duration_value = duration.is_a?(String) ? duration : duration.to_i
+      wait_index = increment_wait_index
+      signal_key = "sleep:#{duration_str}-#{wait_index}"
 
-      # Build the sleep condition
-      sleep_condition = ::V1::SleepMatchCondition.new(
-        base: ::V1::BaseMatchCondition.new(
-          readable_data_key: signal_key,
-          action: :QUEUE,
-          or_group_id: SecureRandom.uuid,
-        ),
-        sleep_for: duration_str,
-      )
-
-      conditions = ::V1::DurableEventListenerConditions.new(
-        sleep_conditions: [sleep_condition],
-      )
-
-      # Register the durable event
-      register_request = ::V1::RegisterDurableEventRequest.new(
-        task_id: @step_run_id,
-        signal_key: signal_key,
-        conditions: conditions,
-      )
-
-      v1_dispatcher_stub.register_durable_event(register_request, metadata: @client.config.auth_metadata)
-
-      # Listen for the durable event via bidi stream
-      listen_for_event(signal_key)
+      wait_for(signal_key, Hatchet::SleepCondition.new(duration_value), label: label)
     end
 
     # Wait for a condition to be met (event or sleep).
     # The task is suspended and resumed when the condition is satisfied.
     #
+    # Register the durable wait with ``send_event`` first, then start eviction
+    # tracking only while blocked on ``wait_for_callback``.
+    #
     # @param key [String] A unique key for this wait operation
     # @param condition [Object] The condition to wait for (UserEventCondition, SleepCondition, Hash, etc.)
+    # @param label [String, nil] Optional wait label shown in durable event logs.
     # @return [Hash] Result from the wait, including which condition was satisfied
-    def wait_for(key, condition)
+    def wait_for(key, condition, label: nil)
       conditions = build_durable_conditions(key, condition)
 
-      # Register the durable event
+      if supports_durable_eviction?
+        invocation = @invocation_count || 1
+
+        event = Hatchet::WorkerRuntime::DurableEventListener::WaitForEvent.new(
+          wait_for_conditions: conditions,
+          label: label,
+        )
+
+        ack = @durable_event_listener.send_event(@step_run_id, invocation, event)
+
+        with_eviction_wait(wait_kind: "wait_for", resource_id: key) do
+          result = @durable_event_listener.wait_for_callback(
+            @step_run_id,
+            invocation,
+            ack[:branch_id],
+            ack[:node_id],
+          )
+
+          result[:payload] || {}
+        end
+      else
+        with_eviction_wait(wait_kind: "wait_for", resource_id: key) do
+          legacy_wait_for(key, conditions)
+        end
+      end
+    end
+
+    private
+
+    # Monotonically increasing per-context wait index, used to disambiguate
+    # multiple sleep/wait calls with otherwise identical resource ids.
+    def increment_wait_index
+      @wait_index ||= 0
+      index = @wait_index
+      @wait_index += 1
+      index
+    end
+
+    # Wrap a block in mark_waiting/mark_active calls on the eviction manager
+    # when one is attached. Safe no-op when not.
+    def with_eviction_wait(wait_kind:, resource_id:)
+      mgr = @eviction_manager
+      key = @action_key
+
+      mgr.mark_waiting(key, wait_kind: wait_kind, resource_id: resource_id) if mgr && key
+
+      begin
+        yield
+      ensure
+        mgr.mark_active(key) if mgr && key
+      end
+    end
+
+    # True when this context can use the durable-eviction bidi protocol.
+    #
+    # Matches the Python SDK's feature-gate naming more closely than
+    # ``use_new_listener?`` while preserving the same behavior here.
+    def supports_durable_eviction?
+      return false unless @durable_event_listener
+      return false unless @engine_version
+
+      !Hatchet::EngineVersion.semver_less_than?(
+        @engine_version,
+        Hatchet::MinEngineVersion::DURABLE_EVICTION,
+      )
+    end
+
+    def legacy_wait_for(key, conditions)
       register_request = ::V1::RegisterDurableEventRequest.new(
         task_id: @step_run_id,
         signal_key: key,
@@ -93,8 +163,6 @@ module Hatchet
       end
     end
 
-    private
-
     # Get or create the V1::V1Dispatcher::Stub for durable events.
     def v1_dispatcher_stub
       @v1_dispatcher_stub ||= ::V1::V1Dispatcher::Stub.new(
@@ -194,7 +262,8 @@ module Hatchet
     def process_durable_condition(key, condition, or_group_id, sleep_conditions, user_event_conditions)
       ConditionConverter.convert_condition(
         condition,
-        action: :QUEUE,
+        # Do not force base.action. Leaving it unset keeps protobuf default semantics on the server path.
+        action: nil,
         sleep_conditions: sleep_conditions,
         user_event_conditions: user_event_conditions,
         or_group_id: or_group_id,

data/lib/hatchet/engine_version.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hatchet
+  # Minimum engine versions required for specific SDK features.
+  #
+  # Mirrors :class:`hatchet_sdk.engine_version.MinEngineVersion` in the
+  # Python SDK.
+  module MinEngineVersion
+    SLOT_CONFIG = "v0.78.23"
+    DURABLE_EVICTION = "v0.80.0"
+    OBSERVABILITY = "v0.82.0"
+  end
+
+  # Semver parsing + comparison helpers used to gate features by engine version.
+  module EngineVersion
+    module_function
+
+    # Parse a semver string like ``"v0.78.23"`` into ``[major, minor, patch]``.
+    #
+    # Returns ``[0, 0, 0]`` if parsing fails, matching the Python helper.
+    #
+    # @param version [String, nil] The version string (with or without a ``v`` prefix, optional ``-pre`` suffix)
+    # @return [Array(Integer, Integer, Integer)]
+    def parse_semver(version)
+      return [0, 0, 0] if version.nil?
+
+      v = version.to_s
+      v = v.sub(/\Av/, "")
+      v = v.split("-", 2).first || ""
+
+      parts = v.split(".")
+      return [0, 0, 0] if parts.length != 3
+
+      [Integer(parts[0]), Integer(parts[1]), Integer(parts[2])]
+    rescue ArgumentError, TypeError
+      [0, 0, 0]
+    end
+
+    # @param left_version [String, nil]
+    # @param right_version [String, nil]
+    # @return [Boolean] true if semver ``left_version`` is strictly less than ``right_version``
+    def semver_less_than?(left_version, right_version)
+      (parse_semver(left_version) <=> parse_semver(right_version)).negative?
+    end
+
+    class << self
+      alias semver_less_than semver_less_than?
+    end
+  end
+end

data/lib/hatchet/eviction_policy.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Hatchet
+  # Task-scoped eviction parameters for *durable* tasks.
+  #
+  # Setting the durable task's eviction policy to ``nil`` means the task run is
+  # never eligible for eviction.
+  #
+  # @example
+  #   Hatchet::EvictionPolicy.new(
+  #     ttl: 600,                     # 10 minutes, in seconds
+  #     allow_capacity_eviction: true,
+  #     priority: 0,
+  #   )
+  class EvictionPolicy
+    # @return [Numeric, nil] Maximum continuous waiting duration in seconds before
+    #   TTL-eligible eviction. Applies to time spent in SDK-instrumented
+    #   "waiting" states (e.g. :meth:`DurableContext#sleep_for`,
+    #   :meth:`DurableContext#wait_for`). ``nil`` disables TTL eviction.
+    attr_reader :ttl
+
+    # @return [Boolean] Whether this task may be evicted under durable-slot pressure.
+    attr_reader :allow_capacity_eviction
+
+    # @return [Integer] Lower values are evicted first when multiple candidates exist.
+    attr_reader :priority
+
+    # @param ttl [Numeric, nil] TTL in seconds (or nil to disable TTL-based eviction)
+    # @param allow_capacity_eviction [Boolean]
+    # @param priority [Integer]
+    def initialize(ttl:, allow_capacity_eviction: true, priority: 0)
+      @ttl = ttl
+      @allow_capacity_eviction = allow_capacity_eviction
+      @priority = priority
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(EvictionPolicy) &&
+        other.ttl == ttl &&
+        other.allow_capacity_eviction == allow_capacity_eviction &&
+        other.priority == priority
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, ttl, allow_capacity_eviction, priority].hash
+    end
+  end
+
+  # Shared sensible defaults.
+  #
+  # NOTE: When changing these values, update the :param eviction_policy: docstrings
+  # in :meth:`Workflow#durable_task` and :meth:`Client#durable_task` to match.
+  DEFAULT_DURABLE_TASK_EVICTION_POLICY = EvictionPolicy.new(
+    ttl: 15 * 60, # 15 minutes
+    allow_capacity_eviction: true,
+    priority: 0,
+  )
+end

data/lib/hatchet/exceptions.rb

@@ -41,6 +41,32 @@ module Hatchet
     end
   end
 
+  # Raised by the engine when durable-task execution detects a non-deterministic
+  # replay (the workflow did something different compared to the recorded log).
+  class NonDeterminismError < Error
+    # @return [String, nil]
+    attr_reader :task_external_id
+    # @return [Integer, nil]
+    attr_reader :invocation_count
+    # @return [Integer, nil]
+    attr_reader :node_id
+
+    def initialize(message, task_external_id: nil, invocation_count: nil, node_id: nil)
+      @task_external_id = task_external_id
+      @invocation_count = invocation_count
+      @node_id = node_id
+      super(message)
+    end
+  end
+
+  # Raised inside a durable task thread when the eviction manager decides to
+  # evict that invocation (e.g. TTL expired, capacity pressure, worker shutdown).
+  class DurableTaskEvictedError < Error
+    def initialize(message = "Durable task evicted")
+      super
+    end
+  end
+
   # Raised when a workflow run fails with one or more task errors
   class FailedRunError < Error
     # @return [Array<TaskRunError>] The individual task run errors

data/lib/hatchet/task.rb

@@ -65,6 +65,9 @@ module Hatchet
     # @return [Boolean] Whether this is a durable task
     attr_reader :durable
 
+    # @return [Hatchet::EvictionPolicy, nil] Eviction policy for durable tasks
+    attr_reader :eviction_policy
+
     # @return [Proc, nil] The task execution block
     attr_reader :fn
 
@@ -108,6 +111,7 @@ module Hatchet
       wait_for: [],
       skip_if: [],
       durable: false,
+      eviction_policy: nil,
       workflow: nil,
       client: nil,
       deps: nil,
@@ -126,6 +130,7 @@ module Hatchet
       @wait_for = wait_for
       @skip_if = skip_if
       @durable = durable
+      @eviction_policy = eviction_policy
       @workflow = workflow
       @client = client
       @deps = deps
@@ -184,6 +189,8 @@ module Hatchet
       conditions_proto = conditions_to_proto(config)
       opts[:conditions] = conditions_proto if conditions_proto
 
+      opts[:is_durable] = @durable
+
       ::V1::CreateTaskOpts.new(**opts)
     end
 

data/lib/hatchet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hatchet
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end