restate-sdk 0.10.0-aarch64-linux → 0.12.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80a62b147724910e3329f4263e61a290ccc55e6f0c097ecc0fad4ece63ef2407
-  data.tar.gz: 33661eccbb66c39e1ca6c57ea735e4ef74fa79a712e05136c7d0624720484ba9
+  metadata.gz: 2cd0022b788463ddb227407d085949183238eb47f8ade847cab75b78890b0200
+  data.tar.gz: f606a03c882e764eef66bb83c87dd0eb74c11032665c4b9d48a348638b1ffbc6
 SHA512:
-  metadata.gz: e0b1fec80f09851613ccb2c4c04ec677566f845b47e51ae5a248d001e4fa9400ed096b574f475551ac3c29e9ca63775a27be799e9876dc2c49a5c4a45e06a466
-  data.tar.gz: 4bbacd32b9999dfdec05918bf7eddb191a2e472b20c977dbab6b898c2bf8b2a6e8600649b2a6bc86fd8072368deab819e96e7b64c642dd2d17434be6084845d2
+  metadata.gz: 6e7b4fbe8225f2a6e06b6a5427738e917c7520aa27260cbead09c3dccdacbdf02899fb5e5c27bceff20eeed02dddd026afedbcf5138c4be13f386525d807f00d
+  data.tar.gz: d756190c93786ffce73f70a0ed109b3547a26ee68dd4c58d55c5c51726fee2adc579fd5ab14a119499b27c41e7a860bbb0547af45638d96bf55c1e013d8c722e

data/Cargo.lock

@@ -561,7 +561,7 @@ dependencies = [
 
 [[package]]
 name = "restate_internal"
-version = "0.10.0"
+version = "0.12.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.12.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/endpoint.rb

@@ -133,8 +133,8 @@ module Restate
 
     # Build and return the Rack-compatible application.
     def app
-      require_relative 'server'
-      Server.new(self)
+      require_relative 'server/handler'
+      Server::Handler.new(self)
     end
 
     private

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