restate-sdk 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40a987e80017804da9524cecb061cb5dd798f63d78b7b9d5297eafd0f7a3f08c
-  data.tar.gz: 7911f4dc802ffc13b5065ee3d7c0447c04a0741dee2df87aa023b7dfd8196cee
+  metadata.gz: 55781f5d8508c22ecf7c6e2a161f658403790fc0538e1028725e0c9c5d33ef0b
+  data.tar.gz: ec0b68be695aaafd60188b54544533a0ee58166a3898a9d9d194b71754678fde
 SHA512:
-  metadata.gz: 8ed57c28f1a19c800602f98d47f8956850fa72962b8a35f6fe80f1d9e27c28d16de8803d504e0000455d8bfdfe45e0e402e063ea330307f4ace1c13c19196316
-  data.tar.gz: e48404e2aa84ee83852b65015fd70330d6407ad3874da6f639af741e623133bb59007294cffdc526ec5b0c1bfe35b20dbe4d9557ae4c1e3f0a92df7c603f6ba8
+  metadata.gz: 31521448b4cb29fc65cf59edbe4c46bfb88216bb565dbe18eff31ed0a58d7b68e80bd2d59ac338d422df424d2b121a96e2171eee692e9cd6a35373746313c69c
+  data.tar.gz: a89ab1dc4a5921fd8cb73f8e9ca85229fb67a6d1468b1109f067bb298158c7022a18ba392f6f9cfd74265b2d0210289a006765e7e267ee77f56f6823eda07db2

data/Cargo.lock

@@ -561,7 +561,7 @@ dependencies = [
 
 [[package]]
 name = "restate_internal"
-version = "0.10.0"
+version = "0.11.0"
 dependencies = [
  "magnus",
  "rb-sys",

data/ext/restate_internal/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "restate_internal"
-version = "0.10.0"
+version = "0.11.0"
 edition = "2021"
 publish = false
 

data/ext/restate_internal/src/lib.rs

@@ -794,6 +794,49 @@ impl RbVM {
             .map_err(core_error_to_magnus)
     }
 
+    // ── Signals ──
+
+    fn sys_signal(&self, signal_name: String) -> Result<u32, Error> {
+        self.vm
+            .borrow_mut()
+            .create_signal_handle(signal_name)
+            .map(Into::into)
+            .map_err(core_error_to_magnus)
+    }
+
+    fn sys_complete_signal_success(
+        &self,
+        target_invocation_id: String,
+        signal_name: String,
+        buffer: RString,
+    ) -> Result<(), Error> {
+        let bytes: Vec<u8> = unsafe { buffer.as_slice().to_vec() };
+        self.vm
+            .borrow_mut()
+            .sys_complete_signal(
+                target_invocation_id,
+                signal_name,
+                NonEmptyValue::Success(bytes.into()),
+            )
+            .map_err(core_error_to_magnus)
+    }
+
+    fn sys_complete_signal_failure(
+        &self,
+        target_invocation_id: String,
+        signal_name: String,
+        failure: &RbFailure,
+    ) -> Result<(), Error> {
+        self.vm
+            .borrow_mut()
+            .sys_complete_signal(
+                target_invocation_id,
+                signal_name,
+                NonEmptyValue::Failure(failure.clone().into()),
+            )
+            .map_err(core_error_to_magnus)
+    }
+
     // ── Cancel invocation ──
 
     fn sys_cancel_invocation(&self, target_invocation_id: String) -> Result<(), Error> {
@@ -1074,6 +1117,15 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "sys_cancel_invocation",
         method!(RbVM::sys_cancel_invocation, 1),
     )?;
+    vm_class.define_method("sys_signal", method!(RbVM::sys_signal, 1))?;
+    vm_class.define_method(
+        "sys_complete_signal_success",
+        method!(RbVM::sys_complete_signal_success, 3),
+    )?;
+    vm_class.define_method(
+        "sys_complete_signal_failure",
+        method!(RbVM::sys_complete_signal_failure, 3),
+    )?;
 
     // IdentityVerifier
     let iv_class = internal.define_class("IdentityVerifier", ruby.class_object())?;

data/lib/restate/context.rb

@@ -135,6 +135,18 @@ module Restate
     # Reject an awakeable with a terminal failure.
     def reject_awakeable(awakeable_id, message, code: 500); end
 
+    # Wait for a named signal addressed to this invocation.
+    # Returns a DurableFuture that resolves once another invocation calls
+    # +resolve_signal+ or +reject_signal+ with the same name targeting this
+    # invocation's id.
+    def signal(name, serde: JsonSerde); end
+
+    # Send a success value to a named signal on another invocation.
+    def resolve_signal(invocation_id, name, payload, serde: JsonSerde); end
+
+    # Send a terminal failure to a named signal on another invocation.
+    def reject_signal(invocation_id, name, message, code: 500); end
+
     # Request cancellation of another invocation.
     def cancel_invocation(invocation_id); end
 

data/lib/restate/middleware/deadlock_detection.rb

@@ -0,0 +1,216 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'base64'
+require 'set'
+
+module Restate
+  module Middleware
+    # Detects VirtualObject deadlocks caused by re-entrant calls to a VO whose
+    # exclusive handler is still running higher up the call chain.
+    #
+    # == The problem
+    #
+    # Restate VirtualObjects serialize exclusive handler access per key. If handler A
+    # on VO key "x" calls handler B on the same VO key "x", the call will block
+    # forever — the key is already locked by A. This is a deadlock.
+    #
+    # == How it works
+    #
+    # This middleware tracks which VO keys are held by the current call chain and
+    # propagates that information via a header on every outbound call.
+    #
+    # === Inbound side
+    #
+    # 1. Reads the held-locks header from the incoming request.
+    # 2. If the current handler is an exclusive VO handler targeting a key already
+    #    in the set → deadlock. Raises a {DeadlockError} immediately.
+    # 3. If this handler is an exclusive VO handler, appends its lock to the set
+    #    so further downstream calls propagate it.
+    #
+    # === Outbound side
+    #
+    # Injects the held-locks header into every outbound service call. When
+    # handler metadata is available (the target service class is known), only
+    # raises for exclusive handlers — shared handler calls are safe. Falls
+    # back to raising for any same-service call when metadata is unavailable
+    # (e.g., calling by string name to an external service).
+    #
+    # == Wire format
+    #
+    # Lock entries are encoded as +base64url(service).base64url(key)+ and
+    # separated by commas. Base64url encoding ensures arbitrary service names
+    # and keys (including those containing +.+, +,+, or non-ASCII characters)
+    # are handled correctly.
+    #
+    # == Journal determinism
+    #
+    # The held-locks header is deterministic across replays: its value depends only
+    # on the execution path, which Restate's journal guarantees is identical on
+    # every replay.
+    #
+    # == Usage
+    #
+    #   endpoint = Restate.endpoint(MyVirtualObject)
+    #   endpoint.use(Restate::Middleware::DeadlockDetection::Inbound)
+    #   endpoint.use_outbound(Restate::Middleware::DeadlockDetection::Outbound)
+    #
+    module DeadlockDetection
+      HEADER = 'x-restate-held-locks'
+      ENTRY_SEPARATOR = ','
+      FIELD_SEPARATOR = '.'
+      DEADLOCK_STATUS_CODE = 409
+
+      THREAD_KEY = :restate_held_exclusive_locks
+
+      class << self
+        # Returns the current set of held exclusive locks for this fiber.
+        # Each entry is a two-element array: [service_name, key].
+        #
+        # @return [Set<Array<String>>]
+        def held_locks
+          Thread.current[THREAD_KEY] || Set.new
+        end
+
+        # @param locks [Set<Array<String>>]
+        def held_locks=(locks)
+          Thread.current[THREAD_KEY] = locks
+        end
+
+        # Encodes a [service, key] pair into a wire-safe string.
+        def encode_lock(service, key)
+          b64_svc = Base64.urlsafe_encode64(service, padding: false)
+          b64_key = Base64.urlsafe_encode64(key, padding: false)
+          "#{b64_svc}#{FIELD_SEPARATOR}#{b64_key}"
+        end
+
+        # Decodes a wire-format lock string into [service, key].
+        # Returns nil if the format is invalid.
+        def decode_lock(encoded)
+          parts = encoded.split(FIELD_SEPARATOR, 2)
+          return nil unless parts.length == 2
+
+          svc = Base64.urlsafe_decode64(parts[0]).force_encoding('UTF-8')
+          key = Base64.urlsafe_decode64(parts[1]).force_encoding('UTF-8')
+          [svc, key]
+        rescue ArgumentError
+          nil
+        end
+
+        # Serializes a set of [service, key] lock pairs into a header value.
+        def encode_header(locks)
+          locks.map { |svc, key| encode_lock(svc, key) }.join(ENTRY_SEPARATOR)
+        end
+
+        # Deserializes a header value into a Set of [service, key] pairs.
+        def decode_header(raw)
+          return Set.new if raw.nil? || raw.to_s.empty?
+
+          entries = raw.to_s.split(ENTRY_SEPARATOR).filter_map do |entry|
+            decode_lock(entry.strip)
+          end
+          Set.new(entries)
+        end
+      end
+
+      # Error raised when a deadlock is detected.
+      #
+      # Uses status code 409 (Conflict) to signal that retrying won't help.
+      class DeadlockError < Restate::TerminalError
+        def initialize(message)
+          super(message, status_code: DEADLOCK_STATUS_CODE)
+        end
+      end
+
+      # Inbound middleware that checks for and tracks VO locks.
+      #
+      # Register with: +endpoint.use(Restate::Middleware::DeadlockDetection::Inbound)+
+      #
+      # @example
+      #   endpoint = Restate.endpoint(MyVirtualObject)
+      #   endpoint.use(Restate::Middleware::DeadlockDetection::Inbound)
+      class Inbound
+        def call(handler, ctx)
+          previous = DeadlockDetection.held_locks
+          incoming = parse_locks(ctx)
+          check_and_track_lock!(handler, ctx, incoming)
+          DeadlockDetection.held_locks = incoming
+          yield
+        ensure
+          DeadlockDetection.held_locks = previous
+        end
+
+        private
+
+        def check_and_track_lock!(handler, ctx, incoming)
+          return unless handler.service_tag.kind == 'object'
+          return unless handler.kind == 'exclusive'
+
+          key = ctx.respond_to?(:key) ? ctx.key : nil
+          return unless key
+
+          svc = handler.service_tag.name
+          lock = [svc, key]
+          raise_deadlock!(svc, handler.name, key, incoming) if incoming.include?(lock)
+          incoming << lock
+        end
+
+        def raise_deadlock!(svc, handler_name, key, locks)
+          held = locks.map { |s, k| "#{s}:#{k}" }.join(', ')
+          msg = "Deadlock detected: #{svc}##{handler_name} on key '#{key}' " \
+                'called while an exclusive handler holds the same VO key. ' \
+                "Held locks: #{held}. " \
+                'This call will never complete.'
+          Kernel.raise DeadlockError, msg
+        end
+
+        def parse_locks(ctx)
+          headers = ctx.request.headers
+          raw = headers.is_a?(Hash) ? headers[HEADER] : nil
+          DeadlockDetection.decode_header(raw)
+        end
+      end
+
+      # Outbound middleware that propagates held locks via headers.
+      #
+      # When handler metadata is available (via Thread.current[:restate_outbound_handler_meta]),
+      # shared handler calls are allowed through — only exclusive handlers can deadlock.
+      # When metadata is unavailable (external service called by string name), falls
+      # back to raising for any same-service call.
+      #
+      # Register with: +endpoint.use_outbound(Restate::Middleware::DeadlockDetection::Outbound)+
+      #
+      # @example
+      #   endpoint = Restate.endpoint(MyVirtualObject)
+      #   endpoint.use_outbound(Restate::Middleware::DeadlockDetection::Outbound)
+      class Outbound
+        def call(service, handler, headers)
+          locks = DeadlockDetection.held_locks
+          propagate_and_check!(service, handler, headers, locks) if locks.any?
+          yield
+        end
+
+        private
+
+        def propagate_and_check!(service, handler, headers, locks)
+          headers[HEADER] = DeadlockDetection.encode_header(locks)
+
+          held_lock = locks.find { |svc, _key| svc == service }
+          return unless held_lock
+
+          return if target_shared?
+
+          msg = "Deadlock detected: outbound call to #{service}##{handler} " \
+                "while exclusive lock held on #{held_lock[0]}:#{held_lock[1]}. " \
+                'This call will block forever.'
+          Kernel.raise DeadlockError, msg
+        end
+
+        def target_shared?
+          meta = Thread.current[:restate_outbound_handler_meta]
+          meta&.kind == 'shared'
+        end
+      end
+    end
+  end
+end

data/lib/restate/server_context.rb

@@ -206,7 +206,7 @@ module Restate
       in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
       out_serde = resolve_serde(output_serde, handler_meta, :output_serde)
       parameter = in_serde.serialize(arg)
-      with_outbound_middleware(svc_name, handler_name, headers) do |hdrs|
+      with_outbound_middleware(svc_name, handler_name, headers, handler_meta: handler_meta) do |hdrs|
         call_handle = @vm.sys_call(
           service: svc_name, handler: handler_name, parameter: parameter,
           key: key, idempotency_key: idempotency_key, headers: hdrs
@@ -223,7 +223,7 @@ module Restate
       in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
       parameter = in_serde.serialize(arg)
       delay_ms = delay ? (delay * 1000).to_i : nil
-      with_outbound_middleware(svc_name, handler_name, headers) do |hdrs|
+      with_outbound_middleware(svc_name, handler_name, headers, handler_meta: handler_meta) do |hdrs|
         invocation_id_handle = @vm.sys_send(
           service: svc_name, handler: handler_name, parameter: parameter,
           key: key, delay: delay_ms, idempotency_key: idempotency_key, headers: hdrs
@@ -239,7 +239,7 @@ module Restate
       in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
       out_serde = resolve_serde(output_serde, handler_meta, :output_serde)
       parameter = in_serde.serialize(arg)
-      with_outbound_middleware(svc_name, handler_name, headers) do |hdrs|
+      with_outbound_middleware(svc_name, handler_name, headers, handler_meta: handler_meta) do |hdrs|
         call_handle = @vm.sys_call(
           service: svc_name, handler: handler_name, parameter: parameter,
           key: key, idempotency_key: idempotency_key, headers: hdrs
@@ -256,7 +256,7 @@ module Restate
       in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
       parameter = in_serde.serialize(arg)
       delay_ms = delay ? (delay * 1000).to_i : nil
-      with_outbound_middleware(svc_name, handler_name, headers) do |hdrs|
+      with_outbound_middleware(svc_name, handler_name, headers, handler_meta: handler_meta) do |hdrs|
         invocation_id_handle = @vm.sys_send(
           service: svc_name, handler: handler_name, parameter: parameter,
           key: key, delay: delay_ms, idempotency_key: idempotency_key, headers: hdrs
@@ -298,6 +298,25 @@ module Restate
       @vm.sys_complete_awakeable_failure(awakeable_id, failure)
     end
 
+    # ── Signals ──
+
+    # Wait for a named signal addressed to this invocation. Returns a DurableFuture.
+    def signal(name, serde: JsonSerde)
+      handle = @vm.sys_signal(name)
+      DurableFuture.new(self, handle, serde: serde)
+    end
+
+    # Send a success value to a named signal on another invocation.
+    def resolve_signal(invocation_id, name, payload, serde: JsonSerde)
+      @vm.sys_complete_signal_success(invocation_id, name, serde.serialize(payload))
+    end
+
+    # Send a terminal failure to a named signal on another invocation.
+    def reject_signal(invocation_id, name, message, code: 500)
+      failure = Failure.new(code: code, message: message)
+      @vm.sys_complete_signal_failure(invocation_id, name, failure)
+    end
+
     # ── Promises (Workflow API) ──
 
     # Gets a durable promise value, blocking until resolved.
@@ -472,18 +491,25 @@ module Restate
     # Runs outbound middleware chain (Sidekiq client middleware pattern).
     # Each middleware gets +call(service, handler, headers)+ and must +yield+
     # to continue the chain. The block at the end performs the actual VM call.
-    def with_outbound_middleware(service, handler, headers, &action)
-      if @outbound_middleware.empty?
-        action.call(headers)
-      else
-        h = headers || {}
-        chain = ->(hdrs) { action.call(hdrs) }
-        @outbound_middleware.reverse_each do |mw|
-          prev = chain
-          chain = ->(hdrs) { mw.call(service, handler, hdrs) { prev.call(hdrs) } }
-        end
-        chain.call(h)
+    #
+    # The optional +handler_meta+ (a Handler struct from resolve_call_target)
+    # is exposed via Thread.current[:restate_outbound_handler_meta] so that
+    # middleware can inspect the target handler's kind without changing the
+    # middleware interface.
+    def with_outbound_middleware(service, handler, headers, handler_meta: nil, &action)
+      return action.call(headers) if @outbound_middleware.empty?
+
+      h = headers || {}
+      previous_meta = Thread.current[:restate_outbound_handler_meta]
+      Thread.current[:restate_outbound_handler_meta] = handler_meta
+      chain = ->(hdrs) { action.call(hdrs) }
+      @outbound_middleware.reverse_each do |mw|
+        prev = chain
+        chain = ->(hdrs) { mw.call(service, handler, hdrs) { prev.call(hdrs) } }
       end
+      chain.call(h)
+    ensure
+      Thread.current[:restate_outbound_handler_meta] = previous_meta
     end
 
     # ── Call target resolution ──

data/lib/restate/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Restate
-  VERSION = '0.10.0'
+  VERSION = '0.11.0'
 end

data/lib/restate/vm.rb

@@ -223,6 +223,19 @@ module Restate
       @vm.sys_cancel_invocation(invocation_id)
     end
 
+    def sys_signal(name)
+      @vm.sys_signal(name)
+    end
+
+    def sys_complete_signal_success(invocation_id, name, value)
+      @vm.sys_complete_signal_success(invocation_id, name, value)
+    end
+
+    def sys_complete_signal_failure(invocation_id, name, failure)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      @vm.sys_complete_signal_failure(invocation_id, name, native_failure)
+    end
+
     private
 
     def map_do_progress(result)

data/lib/restate.rb

@@ -18,6 +18,7 @@ require_relative 'restate/endpoint'
 require_relative 'restate/service_proxy'
 require_relative 'restate/config'
 require_relative 'restate/client'
+require_relative 'restate/middleware/deadlock_detection'
 require_relative 'restate/railtie' if defined?(Rails::Railtie)
 
 # Restate Ruby SDK — build resilient applications with durable execution.
@@ -241,6 +242,23 @@ module Restate # rubocop:disable Metrics/ModuleLength
     fetch_context!.reject_awakeable(awakeable_id, message, code: code)
   end
 
+  # ── Signals ──
+
+  # Wait for a named signal addressed to this invocation. Returns a DurableFuture.
+  def signal(name, serde: JsonSerde)
+    fetch_context!.signal(name, serde: serde)
+  end
+
+  # Send a success value to a named signal on another invocation.
+  def resolve_signal(invocation_id, name, payload, serde: JsonSerde)
+    fetch_context!.resolve_signal(invocation_id, name, payload, serde: serde)
+  end
+
+  # Send a terminal failure to a named signal on another invocation.
+  def reject_signal(invocation_id, name, message, code: 500)
+    fetch_context!.reject_signal(invocation_id, name, message, code: code)
+  end
+
   # ── Promises (Workflow only) ──
 
   # Get a durable promise value, blocking until resolved.

data/sig/restate.rbs

@@ -44,6 +44,12 @@ module Restate
   def self.resolve_awakeable: (String awakeable_id, untyped payload, ?serde: untyped) -> void
   def self.reject_awakeable: (String awakeable_id, String message, ?code: Integer) -> void
 
+  # ── Signals ──
+
+  def self.signal: (String name, ?serde: untyped) -> DurableFuture
+  def self.resolve_signal: (String invocation_id, String name, untyped payload, ?serde: untyped) -> void
+  def self.reject_signal: (String invocation_id, String name, String message, ?code: Integer) -> void
+
   # ── Promises ──
 
   def self.promise: (String name, ?serde: untyped) -> untyped

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restate-sdk
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Restate Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -64,6 +64,7 @@ files:
 - lib/restate/errors.rb
 - lib/restate/handler.rb
 - lib/restate/introspection.rb
+- lib/restate/middleware/deadlock_detection.rb
 - lib/restate/railtie.rb
 - lib/restate/serde.rb
 - lib/restate/server.rb