restate-sdk 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c2177e5412d0b530fcddf1ac29f0ac8caf020169e00499fcf32955c0e818cec
-  data.tar.gz: 216ce2e9488ef6e101ab55784bc4e44caa42bcec7631b4f5ea3ac2591e917691
+  metadata.gz: af00581289bac17d418aea72014305bdd1fd64e3a8d02a0ca6a5194ac1497443
+  data.tar.gz: 3f9dc77d320b092cd074b7e97317893cee9332b0e2a9014c4020b50500ad8701
 SHA512:
-  metadata.gz: f04052cbb2e8e8b98ee26ac6e8f085c11759123e7744e959d6cd4cdcd244da9044f6571dfc66fe8511ec188a50a9bc070f6b02a30dd9a5c60a22414ca524791e
-  data.tar.gz: 9038a6a76a4cde0fe6612921552b9564e4dbe12fcd7db2a9b5d0c3bc04d1f0176c975fbc0b1d43dbcc317ea7d8bd032be090a205e9d3b91cf35738d9fabcfd57
+  metadata.gz: 471fd2f7996b2a03ad7f77d9ed27a0ab5fa03f4f65350292845893b5727165277fc2c7d6b767a5e775dfa26a6b0cd7911bda317b25d7ed19cd35cfd524b3259a
+  data.tar.gz: a0f4f51c113aa455e649a2194bc0b4095110e746122750687017397911dcd3e107eb81f2f8fe1a7feb893fd83c894666157cca2b8c1f487c760ed22d737a05b0

data/Cargo.lock

@@ -830,9 +830,9 @@ checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
 [[package]]
 name = "restate-sdk-shared-core"
-version = "7.0.0"
+version = "7.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9bf02583379fc28d6386bd864629ba6553ce942124956b862fa9e95a4d836558"
+checksum = "8bd1f1d1961ac32aea52923f089e668a07630ca9c4edcadf18d38bc24e5f14c0"
 dependencies = [
  "base64",
  "bs58",
@@ -850,7 +850,7 @@ dependencies = [
 
 [[package]]
 name = "restate_internal"
-version = "1.1.0"
+version = "1.2.0"
 dependencies = [
  "magnus",
  "rb-sys",

data/ext/restate_internal/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "restate_internal"
-version = "1.1.0"
+version = "1.2.0"
 edition = "2021"
 publish = false
 
@@ -12,5 +12,5 @@ doc = false
 [dependencies]
 magnus = { version = "0.8", features = ["rb-sys"] }
 rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
-restate-sdk-shared-core = { version = "7.0.0" , features = ["request_identity", "sha2_random_seed", "rust_crypto"] }
+restate-sdk-shared-core = { version = "7.0.1" , features = ["request_identity", "sha2_random_seed", "rust_crypto"] }
 tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter"] }

data/ext/restate_internal/src/lib.rs

@@ -215,6 +215,9 @@ struct RbInput {
     key: String,
     headers: Vec<RbHeader>,
     input: Vec<u8>,
+    scope: Option<String>,
+    limit_key: Option<String>,
+    idempotency_key: Option<String>,
 }
 
 impl RbInput {
@@ -227,6 +230,15 @@ impl RbInput {
     fn key(&self) -> &str {
         &self.key
     }
+    fn scope(&self) -> Option<&str> {
+        self.scope.as_deref()
+    }
+    fn limit_key(&self) -> Option<&str> {
+        self.limit_key.as_deref()
+    }
+    fn idempotency_key(&self) -> Option<&str> {
+        self.idempotency_key.as_deref()
+    }
     fn headers_array(&self) -> Result<RArray, Error> {
         let ruby = Ruby::get().map_err(|_| Error::new(vm_error_class(), "Ruby not available"))?;
         let ary = ruby.ary_new_capa(self.headers.len());
@@ -249,6 +261,9 @@ impl From<Input> for RbInput {
             key: i.key,
             headers: i.headers.into_iter().map(Into::into).collect(),
             input: i.input.into(),
+            scope: i.scope,
+            limit_key: i.limit_key,
+            idempotency_key: i.idempotency_key,
         }
     }
 }
@@ -584,7 +599,9 @@ impl RbVM {
             .map_err(core_error_to_magnus)
     }
 
-    // sys_call(service, handler, buffer, key_or_nil, idempotency_key_or_nil, headers_or_nil)
+    // sys_call(service, handler, buffer, key_or_nil, idempotency_key_or_nil, headers_or_nil,
+    //          scope_or_nil, limit_key_or_nil)
+    #[allow(clippy::too_many_arguments)]
     fn sys_call(
         &self,
         service: String,
@@ -593,6 +610,8 @@ impl RbVM {
         key: Value,
         idempotency_key: Value,
         headers: Value,
+        scope: Value,
+        limit_key: Value,
     ) -> Result<RbCallHandle, Error> {
         let bytes: Vec<u8> = unsafe { buffer.as_slice().to_vec() };
         let key_opt: Option<String> = if key.is_nil() {
@@ -610,6 +629,16 @@ impl RbVM {
         } else {
             parse_headers_array(RArray::try_convert(headers)?)?
         };
+        let scope_opt: Option<String> = if scope.is_nil() {
+            None
+        } else {
+            Some(String::try_convert(scope)?)
+        };
+        let limit_key_opt: Option<String> = if limit_key.is_nil() {
+            None
+        } else {
+            Some(String::try_convert(limit_key)?)
+        };
         self.vm
             .borrow_mut()
             .sys_call(
@@ -618,8 +647,8 @@ impl RbVM {
                     handler,
                     key: key_opt,
                     idempotency_key: idem_opt,
-                    scope: None,
-                    limit_key: None,
+                    scope: scope_opt,
+                    limit_key: limit_key_opt,
                     headers: hdr_vec,
                 },
                 bytes.into(),
@@ -630,7 +659,9 @@ impl RbVM {
             .map_err(core_error_to_magnus)
     }
 
-    // sys_send(service, handler, buffer, key_or_nil, delay_or_nil, idempotency_key_or_nil, headers_or_nil)
+    // sys_send(service, handler, buffer, key_or_nil, delay_or_nil, idempotency_key_or_nil,
+    //          headers_or_nil, scope_or_nil, limit_key_or_nil)
+    #[allow(clippy::too_many_arguments)]
     fn sys_send(
         &self,
         service: String,
@@ -640,6 +671,8 @@ impl RbVM {
         delay: Value,
         idempotency_key: Value,
         headers: Value,
+        scope: Value,
+        limit_key: Value,
     ) -> Result<u32, Error> {
         let bytes: Vec<u8> = unsafe { buffer.as_slice().to_vec() };
         let key_opt: Option<String> = if key.is_nil() {
@@ -662,6 +695,16 @@ impl RbVM {
         } else {
             parse_headers_array(RArray::try_convert(headers)?)?
         };
+        let scope_opt: Option<String> = if scope.is_nil() {
+            None
+        } else {
+            Some(String::try_convert(scope)?)
+        };
+        let limit_key_opt: Option<String> = if limit_key.is_nil() {
+            None
+        } else {
+            Some(String::try_convert(limit_key)?)
+        };
         self.vm
             .borrow_mut()
             .sys_send(
@@ -670,8 +713,8 @@ impl RbVM {
                     handler,
                     key: key_opt,
                     idempotency_key: idem_opt,
-                    scope: None,
-                    limit_key: None,
+                    scope: scope_opt,
+                    limit_key: limit_key_opt,
                     headers: hdr_vec,
                 },
                 bytes.into(),
@@ -1135,6 +1178,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     input_class.define_method("invocation_id", method!(RbInput::invocation_id, 0))?;
     input_class.define_method("random_seed", method!(RbInput::random_seed, 0))?;
     input_class.define_method("key", method!(RbInput::key, 0))?;
+    input_class.define_method("scope", method!(RbInput::scope, 0))?;
+    input_class.define_method("limit_key", method!(RbInput::limit_key, 0))?;
+    input_class.define_method("idempotency_key", method!(RbInput::idempotency_key, 0))?;
     input_class.define_method("headers", method!(RbInput::headers_array, 0))?;
     input_class.define_method("input", method!(RbInput::input_bytes, 0))?;
 
@@ -1189,8 +1235,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     vm_class.define_method("sys_clear_state", method!(RbVM::sys_clear_state, 1))?;
     vm_class.define_method("sys_clear_all_state", method!(RbVM::sys_clear_all_state, 0))?;
     vm_class.define_method("sys_sleep", method!(RbVM::sys_sleep, 2))?;
-    vm_class.define_method("sys_call", method!(RbVM::sys_call, 6))?;
-    vm_class.define_method("sys_send", method!(RbVM::sys_send, 7))?;
+    vm_class.define_method("sys_call", method!(RbVM::sys_call, 8))?;
+    vm_class.define_method("sys_send", method!(RbVM::sys_send, 9))?;
     vm_class.define_method("sys_run", method!(RbVM::sys_run, 1))?;
     vm_class.define_method(
         "propose_run_completion_success",

data/lib/restate/context.rb

@@ -63,7 +63,14 @@ module Restate
   #   @return [String] raw input bytes
   # @!attribute [r] attempt_finished_event
   #   @return [AttemptFinishedEvent] signaled when this attempt ends
-  Request = Struct.new(:id, :headers, :body, :attempt_finished_event, keyword_init: true)
+  # @!attribute [r] scope
+  #   @return [String, nil] the scope this invocation was routed within, if any
+  # @!attribute [r] limit_key
+  #   @return [String, nil] the concurrency limit key this invocation was made with, if any
+  # @!attribute [r] idempotency_key
+  #   @return [String, nil] the idempotency key this invocation was made with, if any
+  Request = Struct.new(:id, :headers, :body, :attempt_finished_event,
+                       :scope, :limit_key, :idempotency_key, keyword_init: true)
 
   # Base context interface for all Restate handlers.
   #
@@ -120,10 +127,37 @@ module Restate
     end
 
     # Durably call a handler using raw bytes (no serialization).
-    def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil); end
+    def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil,
+                     scope: nil, limit_key: nil)
+    end
 
     # Fire-and-forget send using raw bytes (no serialization).
-    def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil); end
+    def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil,
+                     scope: nil, limit_key: nil)
+    end
+
+    # Returns a +ScopedContext+ that routes all outgoing calls within the given scope.
+    #
+    # NOTE: This API is in preview and is not enabled by default. To use it in
+    # restate-server 1.7, enable the flow control and protocol v7 experimental
+    # features via +RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true+ and
+    # +RESTATE_EXPERIMENTAL_ENABLE_VQUEUES=true+. These can be enabled only on new
+    # clusters. If they aren't enabled, the call fails with a retryable error and
+    # keeps retrying until they are.
+    #
+    # A scope is a sub-grouping of resources (invocations, workflow instances,
+    # concurrency limits) within the Restate cluster. It becomes part of the target
+    # identity tuple and contributes to the partition key, so all resources in a
+    # scope get co-located by the restate-server. Omitting the scope (i.e. using the
+    # regular +service_call+ / +workflow_call+ methods) is equivalent to calling
+    # with no scope, which is the existing behavior.
+    #
+    # The scope must consist only of +[a-zA-Z0-9_.-]+ characters, 1 <= length <= 36.
+    #
+    # @param scope [String] the scope identifier
+    # @return [ScopedContext]
+    # @see https://docs.restate.dev/services/flow-control
+    def scope(scope); end
 
     # Create an awakeable for external callbacks.
     # Returns [awakeable_id, DurableFuture].

data/lib/restate/server/context.rb

@@ -243,8 +243,11 @@ module Restate
       # ── Service calls ──
 
       # Durably calls a handler on a Restate service and returns a future for its result.
+      #
+      # +scope+ and +limit_key+ are internal parameters set by +ScopedContext+
+      # (via +ctx.scope(...)+); prefer that API over passing them directly.
       def service_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil,
-                       input_serde: NOT_SET, output_serde: NOT_SET)
+                       input_serde: NOT_SET, output_serde: NOT_SET, scope: nil, limit_key: nil)
         svc_name, handler_name, handler_meta = resolve_call_target(service, handler)
         in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
         out_serde = resolve_serde(output_serde, handler_meta, :output_serde)
@@ -252,7 +255,7 @@ module Restate
         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
+            key: key, idempotency_key: idempotency_key, headers: hdrs, scope: scope, limit_key: limit_key
           )
           DurableCallFuture.new(self, call_handle.result_handle, call_handle.invocation_id_handle,
                                 output_serde: out_serde)
@@ -260,8 +263,11 @@ module Restate
       end
 
       # Sends a one-way invocation to a Restate service handler (fire-and-forget).
+      #
+      # +scope+ and +limit_key+ are internal parameters set by +ScopedContext+
+      # (via +ctx.scope(...)+); prefer that API over passing them directly.
       def service_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil,
-                       input_serde: NOT_SET)
+                       input_serde: NOT_SET, scope: nil, limit_key: nil)
         svc_name, handler_name, handler_meta = resolve_call_target(service, handler)
         in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
         parameter = in_serde.serialize(arg)
@@ -269,15 +275,19 @@ module Restate
         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
+            key: key, delay: delay_ms, idempotency_key: idempotency_key, headers: hdrs,
+            scope: scope, limit_key: limit_key
           )
           SendHandle.new(self, invocation_id_handle)
         end
       end
 
       # Durably calls a handler on a Restate virtual object, keyed by +key+.
+      #
+      # +scope+ and +limit_key+ are internal parameters set by +ScopedContext+
+      # (via +ctx.scope(...)+); prefer that API over passing them directly.
       def object_call(service, handler, key, arg, idempotency_key: nil, headers: nil,
-                      input_serde: NOT_SET, output_serde: NOT_SET)
+                      input_serde: NOT_SET, output_serde: NOT_SET, scope: nil, limit_key: nil)
         svc_name, handler_name, handler_meta = resolve_call_target(service, handler)
         in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
         out_serde = resolve_serde(output_serde, handler_meta, :output_serde)
@@ -285,7 +295,7 @@ module Restate
         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
+            key: key, idempotency_key: idempotency_key, headers: hdrs, scope: scope, limit_key: limit_key
           )
           DurableCallFuture.new(self, call_handle.result_handle, call_handle.invocation_id_handle,
                                 output_serde: out_serde)
@@ -293,8 +303,11 @@ module Restate
       end
 
       # Sends a one-way invocation to a Restate virtual object handler (fire-and-forget).
+      #
+      # +scope+ and +limit_key+ are internal parameters set by +ScopedContext+
+      # (via +ctx.scope(...)+); prefer that API over passing them directly.
       def object_send(service, handler, key, arg, delay: nil, idempotency_key: nil, headers: nil,
-                      input_serde: NOT_SET)
+                      input_serde: NOT_SET, scope: nil, limit_key: nil)
         svc_name, handler_name, handler_meta = resolve_call_target(service, handler)
         in_serde = resolve_serde(input_serde, handler_meta, :input_serde)
         parameter = in_serde.serialize(arg)
@@ -302,24 +315,38 @@ module Restate
         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
+            key: key, delay: delay_ms, idempotency_key: idempotency_key, headers: hdrs,
+            scope: scope, limit_key: limit_key
           )
           SendHandle.new(self, invocation_id_handle)
         end
       end
 
       # Durably calls a handler on a Restate workflow, keyed by +key+.
+      #
+      # +scope+ and +limit_key+ are internal parameters set by +ScopedContext+
+      # (via +ctx.scope(...)+); prefer that API over passing them directly.
       def workflow_call(service, handler, key, arg, idempotency_key: nil, headers: nil,
-                        input_serde: NOT_SET, output_serde: NOT_SET)
-        object_call(service, handler, key, arg, idempotency_key: idempotency_key, headers: headers,
-                    input_serde: input_serde, output_serde: output_serde) # rubocop:disable Layout/HashAlignment
+                        input_serde: NOT_SET, output_serde: NOT_SET, scope: nil, limit_key: nil)
+        object_call(
+          service, handler, key, arg,
+          idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, output_serde: output_serde,
+          scope: scope, limit_key: limit_key
+        )
       end
 
       # Sends a one-way invocation to a Restate workflow handler (fire-and-forget).
+      #
+      # +scope+ and +limit_key+ are internal parameters set by +ScopedContext+
+      # (via +ctx.scope(...)+); prefer that API over passing them directly.
       def workflow_send(service, handler, key, arg, delay: nil, idempotency_key: nil, headers: nil,
-                        input_serde: NOT_SET)
-        object_send(service, handler, key, arg, delay: delay, idempotency_key: idempotency_key, headers: headers,
-                    input_serde: input_serde) # rubocop:disable Layout/HashAlignment
+                        input_serde: NOT_SET, scope: nil, limit_key: nil)
+        object_send(
+          service, handler, key, arg,
+          delay: delay, idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, scope: scope, limit_key: limit_key
+        )
       end
 
       # ── Awakeables ──
@@ -403,11 +430,15 @@ module Restate
       # ── Generic calls (raw bytes, no serde) ──
 
       # Durably calls a handler using raw bytes (no serialization). Useful for proxying.
-      def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil)
+      #
+      # Optionally accepts a +scope+ to route the call within (see +#scope+) and a
+      # +limit_key+ to enforce hierarchical concurrency limits within that scope.
+      def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil,
+                       scope: nil, limit_key: nil)
         with_outbound_middleware(service, handler, headers) do |hdrs|
           call_handle = @vm.sys_call(
             service: service, handler: handler, parameter: arg,
-            key: key, idempotency_key: idempotency_key, headers: hdrs
+            key: key, idempotency_key: idempotency_key, headers: hdrs, scope: scope, limit_key: limit_key
           )
           DurableCallFuture.new(self, call_handle.result_handle, call_handle.invocation_id_handle,
                                 output_serde: nil)
@@ -415,26 +446,42 @@ module Restate
       end
 
       # Sends a one-way invocation using raw bytes (no serialization). Useful for proxying.
-      def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil)
+      #
+      # Optionally accepts a +scope+ to route the send within (see +#scope+) and a
+      # +limit_key+ to enforce hierarchical concurrency limits within that scope.
+      def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil,
+                       scope: nil, limit_key: nil)
         delay_ms = delay ? (delay * 1000).to_i : nil
         with_outbound_middleware(service, handler, headers) do |hdrs|
           invocation_id_handle = @vm.sys_send(
             service: service, handler: handler, parameter: arg,
-            key: key, delay: delay_ms, idempotency_key: idempotency_key, headers: hdrs
+            key: key, delay: delay_ms, idempotency_key: idempotency_key, headers: hdrs,
+            scope: scope, limit_key: limit_key
           )
           SendHandle.new(self, invocation_id_handle)
         end
       end
 
+      # Returns a +ScopedContext+ that routes all outgoing calls within the given scope.
+      # See {Restate::Context#scope} for the full semantics and constraints.
+      def scope(scope)
+        ScopedContext.new(self, scope)
+      end
+
       # ── Request metadata ──
 
-      # Returns metadata about the current invocation (id, headers, raw body).
+      # Returns metadata about the current invocation (id, headers, raw body,
+      # and — when present — the scope, limit_key, and idempotency_key it was
+      # invoked with).
       def request
         @request ||= Request.new(
           id: @invocation.invocation_id,
           headers: @invocation.headers.to_h,
           body: @invocation.input_buffer,
-          attempt_finished_event: @attempt_finished_event
+          attempt_finished_event: @attempt_finished_event,
+          scope: @invocation.scope,
+          limit_key: @invocation.limit_key,
+          idempotency_key: @invocation.idempotency_key
         )
       end
 
@@ -737,5 +784,92 @@ module Restate
         end
       end
     end
+
+    # A context for making RPC calls within a specific scope.
+    #
+    # NOTE: This API is in preview and is not enabled by default. See
+    # {Restate::Context#scope} for how to enable it and for the full semantics.
+    #
+    # Returned by +ctx.scope(scope)+: calls and sends made through this context
+    # carry the captured scope, and each method additionally accepts an optional
+    # +limit_key+.
+    #
+    # The limit key enforces hierarchical concurrency limits on invocations sharing
+    # the same scope. It can have one or two levels separated by +/+ (e.g. +"tenant1"+
+    # or +"tenant1/user42"+). Each level must consist only of +[a-zA-Z0-9_.-]+
+    # characters, 1 <= length <= 36.
+    #
+    # The limit key is *not* part of the request identity: two calls to the same
+    # target with the same scope and object key but different limit keys refer to the
+    # *same* resource instance. The limit key only affects concurrency limits.
+    class ScopedContext
+      def initialize(ctx, scope)
+        @ctx = ctx
+        @scope = scope
+      end
+
+      # Durably calls a handler on a Restate service, within this scope.
+      def service_call(service, handler, arg, key: nil, limit_key: nil, idempotency_key: nil,
+                       headers: nil, input_serde: NOT_SET, output_serde: NOT_SET)
+        @ctx.service_call(
+          service, handler, arg,
+          key: key, idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, output_serde: output_serde,
+          scope: @scope, limit_key: limit_key
+        )
+      end
+
+      # Fire-and-forget send to a Restate service handler, within this scope.
+      def service_send(service, handler, arg, key: nil, delay: nil, limit_key: nil,
+                       idempotency_key: nil, headers: nil, input_serde: NOT_SET)
+        @ctx.service_send(
+          service, handler, arg,
+          key: key, delay: delay, idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, scope: @scope, limit_key: limit_key
+        )
+      end
+
+      # Durably calls a handler on a Restate virtual object, within this scope.
+      def object_call(service, handler, key, arg, limit_key: nil, idempotency_key: nil,
+                      headers: nil, input_serde: NOT_SET, output_serde: NOT_SET)
+        @ctx.object_call(
+          service, handler, key, arg,
+          idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, output_serde: output_serde,
+          scope: @scope, limit_key: limit_key
+        )
+      end
+
+      # Fire-and-forget send to a Restate virtual object handler, within this scope.
+      def object_send(service, handler, key, arg, delay: nil, limit_key: nil,
+                      idempotency_key: nil, headers: nil, input_serde: NOT_SET)
+        @ctx.object_send(
+          service, handler, key, arg,
+          delay: delay, idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, scope: @scope, limit_key: limit_key
+        )
+      end
+
+      # Durably calls a handler on a Restate workflow, within this scope.
+      def workflow_call(service, handler, key, arg, limit_key: nil, idempotency_key: nil,
+                        headers: nil, input_serde: NOT_SET, output_serde: NOT_SET)
+        @ctx.workflow_call(
+          service, handler, key, arg,
+          idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, output_serde: output_serde,
+          scope: @scope, limit_key: limit_key
+        )
+      end
+
+      # Fire-and-forget send to a Restate workflow handler, within this scope.
+      def workflow_send(service, handler, key, arg, delay: nil, limit_key: nil,
+                        idempotency_key: nil, headers: nil, input_serde: NOT_SET)
+        @ctx.workflow_send(
+          service, handler, key, arg,
+          delay: delay, idempotency_key: idempotency_key, headers: headers,
+          input_serde: input_serde, scope: @scope, limit_key: limit_key
+        )
+      end
+    end
   end
 end

data/lib/restate/service.rb

@@ -33,10 +33,13 @@ module Restate
     #
     # @example
     #   Greeter.call.greet("World").await
+    #   Greeter.call(scope: "tenant1", limit_key: "tenant1/user42").greet("World").await
     #
+    # @param scope [String, nil] optional scope to route the call within (see {Restate.scope})
+    # @param limit_key [String, nil] optional concurrency limit key within the scope
     # @return [ServiceCallProxy]
-    def self.call
-      ServiceCallProxy.new(self, call_method: :service_call)
+    def self.call(scope: nil, limit_key: nil)
+      ServiceCallProxy.new(self, call_method: :service_call, scope: scope, limit_key: limit_key)
     end
 
     # Returns a send proxy for fluent fire-and-forget sends to this service.
@@ -44,11 +47,14 @@ module Restate
     # @example
     #   Greeter.send!.greet("World")
     #   Greeter.send!(delay: 60).greet("World")
+    #   Greeter.send!(scope: "tenant1", limit_key: "tenant1/user42").greet("World")
     #
     # @param delay [Numeric, nil] optional delay in seconds
+    # @param scope [String, nil] optional scope to route the send within (see {Restate.scope})
+    # @param limit_key [String, nil] optional concurrency limit key within the scope
     # @return [ServiceSendProxy]
-    def self.send!(delay: nil)
-      ServiceSendProxy.new(self, send_method: :service_send, delay: delay)
+    def self.send!(delay: nil, scope: nil, limit_key: nil)
+      ServiceSendProxy.new(self, send_method: :service_send, delay: delay, scope: scope, limit_key: limit_key)
     end
 
     def self._service_kind

data/lib/restate/service_proxy.rb

@@ -14,16 +14,23 @@ module Restate
   #   # Instead of: ctx.object_call(Counter, :add, "key", 5)
   #   Counter.call("key").add(5)
   #
+  #   # Scoped call (preview): route within a scope with an optional limit key
+  #   Greeter.call(scope: "tenant1", limit_key: "tenant1/user42").greet("World")
+  #
   # @!visibility private
   class ServiceCallProxy
-    def initialize(service_class, key: nil, call_method: :service_call)
+    def initialize(service_class, key: nil, call_method: :service_call, scope: nil, limit_key: nil)
       @service_class = service_class
       @key = key
       @call_method = call_method
+      @scope = scope
+      @limit_key = limit_key
     end
 
     def method_missing(handler_name, arg = nil, **opts)
       ctx = Restate.fetch_context!
+      opts[:scope] = @scope unless @scope.nil? || opts.key?(:scope)
+      opts[:limit_key] = @limit_key unless @limit_key.nil? || opts.key?(:limit_key)
       if @key
         ctx.public_send(@call_method, @service_class, handler_name, @key, arg, **opts)
       else
@@ -47,18 +54,25 @@ module Restate
   #   # Instead of: ctx.object_send(Counter, :add, "key", 5, delay: 60)
   #   Counter.send!("key", delay: 60).add(5)
   #
+  #   # Scoped send (preview): route within a scope with an optional limit key
+  #   Greeter.send!(scope: "tenant1", limit_key: "tenant1/user42").greet("World")
+  #
   # @!visibility private
   class ServiceSendProxy
-    def initialize(service_class, key: nil, send_method: :service_send, delay: nil)
+    def initialize(service_class, key: nil, send_method: :service_send, delay: nil, scope: nil, limit_key: nil)
       @service_class = service_class
       @key = key
       @send_method = send_method
       @delay = delay
+      @scope = scope
+      @limit_key = limit_key
     end
 
     def method_missing(handler_name, arg = nil, **opts)
       ctx = Restate.fetch_context!
       opts[:delay] = @delay if @delay
+      opts[:scope] = @scope unless @scope.nil? || opts.key?(:scope)
+      opts[:limit_key] = @limit_key unless @limit_key.nil? || opts.key?(:limit_key)
       if @key
         ctx.public_send(@send_method, @service_class, handler_name, @key, arg, **opts)
       else

data/lib/restate/version.rb

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

data/lib/restate/virtual_object.rb

@@ -52,11 +52,14 @@ module Restate
     #
     # @example
     #   Counter.call("my-key").add(5).await
+    #   Counter.call("my-key", scope: "tenant1", limit_key: "tenant1/user42").add(5).await
     #
     # @param key [String] the object key
+    # @param scope [String, nil] optional scope to route the call within (see {Restate.scope})
+    # @param limit_key [String, nil] optional concurrency limit key within the scope
     # @return [ServiceCallProxy]
-    def self.call(key)
-      ServiceCallProxy.new(self, key: key, call_method: :object_call)
+    def self.call(key, scope: nil, limit_key: nil)
+      ServiceCallProxy.new(self, key: key, call_method: :object_call, scope: scope, limit_key: limit_key)
     end
 
     # Returns a send proxy for fluent fire-and-forget sends to this virtual object.
@@ -64,12 +67,15 @@ module Restate
     # @example
     #   Counter.send!("my-key").add(5)
     #   Counter.send!("my-key", delay: 60).add(5)
+    #   Counter.send!("my-key", scope: "tenant1", limit_key: "tenant1/user42").add(5)
     #
     # @param key [String] the object key
     # @param delay [Numeric, nil] optional delay in seconds
+    # @param scope [String, nil] optional scope to route the send within (see {Restate.scope})
+    # @param limit_key [String, nil] optional concurrency limit key within the scope
     # @return [ServiceSendProxy]
-    def self.send!(key, delay: nil)
-      ServiceSendProxy.new(self, key: key, send_method: :object_send, delay: delay)
+    def self.send!(key, delay: nil, scope: nil, limit_key: nil)
+      ServiceSendProxy.new(self, key: key, send_method: :object_send, delay: delay, scope: scope, limit_key: limit_key)
     end
 
     def self._service_kind

data/lib/restate/vm.rb

@@ -18,7 +18,8 @@ end
 
 module Restate
   # Ruby-side data types for VM results
-  Invocation = Struct.new(:invocation_id, :random_seed, :headers, :input_buffer, :key, keyword_init: true)
+  Invocation = Struct.new(:invocation_id, :random_seed, :headers, :input_buffer, :key,
+                          :scope, :limit_key, :idempotency_key, keyword_init: true)
   Failure = Struct.new(:code, :message, :stacktrace, :metadata, keyword_init: true)
 
   class NotReady; end
@@ -116,7 +117,10 @@ module Restate
         random_seed: inp.random_seed,
         headers: headers,
         input_buffer: inp.input.b,
-        key: inp.key
+        key: inp.key,
+        scope: inp.scope,
+        limit_key: inp.limit_key,
+        idempotency_key: inp.idempotency_key
       )
     end
 
@@ -145,16 +149,19 @@ module Restate
       @vm.sys_sleep(millis, name)
     end
 
-    def sys_call(service:, handler:, parameter:, key: nil, idempotency_key: nil, headers: nil)
-      # Rust side expects 6 args: (service, handler, buffer, key_or_nil, idem_key_or_nil, headers_or_nil)
+    def sys_call(service:, handler:, parameter:, key: nil, idempotency_key: nil, headers: nil,
+                 scope: nil, limit_key: nil)
+      # Rust side expects 8 args:
+      # (service, handler, buffer, key_or_nil, idem_key_or_nil, headers_or_nil, scope_or_nil, limit_key_or_nil)
       hdr_array = headers&.map { |k, v| [k, v] }
-      @vm.sys_call(service, handler, parameter, key, idempotency_key, hdr_array)
+      @vm.sys_call(service, handler, parameter, key, idempotency_key, hdr_array, scope, limit_key)
     end
 
-    def sys_send(service:, handler:, parameter:, key: nil, delay: nil, idempotency_key: nil, headers: nil)
-      # Rust side expects 7 args
+    def sys_send(service:, handler:, parameter:, key: nil, delay: nil, idempotency_key: nil, headers: nil,
+                 scope: nil, limit_key: nil)
+      # Rust side expects 9 args
       hdr_array = headers&.map { |k, v| [k, v] }
-      @vm.sys_send(service, handler, parameter, key, delay, idempotency_key, hdr_array)
+      @vm.sys_send(service, handler, parameter, key, delay, idempotency_key, hdr_array, scope, limit_key)
     end
 
     def sys_run(name)

data/lib/restate/workflow.rb

@@ -52,11 +52,14 @@ module Restate
     #
     # @example
     #   UserSignup.call("user42").run("user@example.com").await
+    #   UserSignup.call("user42", scope: "tenant1", limit_key: "tenant1/user42").run(email).await
     #
     # @param key [String] the workflow key
+    # @param scope [String, nil] optional scope to route the call within (see {Restate.scope})
+    # @param limit_key [String, nil] optional concurrency limit key within the scope
     # @return [ServiceCallProxy]
-    def self.call(key)
-      ServiceCallProxy.new(self, key: key, call_method: :workflow_call)
+    def self.call(key, scope: nil, limit_key: nil)
+      ServiceCallProxy.new(self, key: key, call_method: :workflow_call, scope: scope, limit_key: limit_key)
     end
 
     # Returns a send proxy for fluent fire-and-forget sends to this workflow.
@@ -64,12 +67,19 @@ module Restate
     # @example
     #   UserSignup.send!("user42").run("user@example.com")
     #   UserSignup.send!("user42", delay: 60).run("user@example.com")
+    #   UserSignup.send!("user42", scope: "tenant1", limit_key: "tenant1/user42").run(email)
     #
     # @param key [String] the workflow key
     # @param delay [Numeric, nil] optional delay in seconds
+    # @param scope [String, nil] optional scope to route the send within (see {Restate.scope})
+    # @param limit_key [String, nil] optional concurrency limit key within the scope
     # @return [ServiceSendProxy]
-    def self.send!(key, delay: nil)
-      ServiceSendProxy.new(self, key: key, send_method: :workflow_send, delay: delay)
+    def self.send!(key, delay: nil, scope: nil, limit_key: nil)
+      ServiceSendProxy.new(
+        self,
+        key: key, send_method: :workflow_send,
+        delay: delay, scope: scope, limit_key: limit_key
+      )
     end
 
     def self._service_kind

data/lib/restate.rb

@@ -219,15 +219,27 @@ module Restate # rubocop:disable Metrics/ModuleLength
   end
 
   # Durably call a handler using raw bytes (no serialization).
-  def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil)
-    fetch_context!.generic_call(service, handler, arg, key: key,
-                                                       idempotency_key: idempotency_key, headers: headers)
+  def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil,
+                   scope: nil, limit_key: nil)
+    fetch_context!.generic_call(service, handler, arg, key: key, idempotency_key: idempotency_key,
+                                                       headers: headers, scope: scope, limit_key: limit_key)
   end
 
   # Fire-and-forget send using raw bytes (no serialization).
-  def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil)
+  def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil,
+                   scope: nil, limit_key: nil)
     fetch_context!.generic_send(service, handler, arg, key: key, delay: delay,
-                                                       idempotency_key: idempotency_key, headers: headers)
+                                                       idempotency_key: idempotency_key, headers: headers,
+                                                       scope: scope, limit_key: limit_key)
+  end
+
+  # Returns a +ScopedContext+ that routes all outgoing calls within the given scope.
+  # See {Restate::Context#scope} for the full semantics and constraints.
+  #
+  # @example
+  #   Restate.scope("tenant1").service_call(Greeter, :greet, "World", limit_key: "tenant1/user42")
+  def scope(scope)
+    fetch_context!.scope(scope)
   end
 
   # ── Awakeables ──

data/sig/restate.rbs

@@ -35,8 +35,9 @@ module Restate
   def self.object_send: (untyped service, (String | Symbol) handler, String key, untyped arg, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
   def self.workflow_call: (untyped service, (String | Symbol) handler, String key, untyped arg, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
   def self.workflow_send: (untyped service, (String | Symbol) handler, String key, untyped arg, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
-  def self.generic_call: (String service, String handler, String arg, ?key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?) -> DurableCallFuture
-  def self.generic_send: (String service, String handler, String arg, ?key: String?, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?) -> SendHandle
+  def self.generic_call: (String service, String handler, String arg, ?key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?scope: String?, ?limit_key: String?) -> DurableCallFuture
+  def self.generic_send: (String service, String handler, String arg, ?key: String?, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?scope: String?, ?limit_key: String?) -> SendHandle
+  def self.scope: (String scope) -> Server::ScopedContext
 
   # ── Awakeables ──
 
@@ -197,11 +198,11 @@ module Restate
   # ── Service proxies ──
 
   class ServiceCallProxy
-    def initialize: (untyped service_class, ?key: String?, ?call_method: Symbol) -> void
+    def initialize: (untyped service_class, ?key: String?, ?call_method: Symbol, ?scope: String?, ?limit_key: String?) -> void
   end
 
   class ServiceSendProxy
-    def initialize: (untyped service_class, ?key: String?, ?send_method: Symbol, ?delay: Numeric?) -> void
+    def initialize: (untyped service_class, ?key: String?, ?send_method: Symbol, ?delay: Numeric?, ?scope: String?, ?limit_key: String?) -> void
   end
 
   # ── Service classes (declared but not checked — heavy metaprogramming) ──
@@ -225,6 +226,16 @@ module Restate
 
     class Context
     end
+
+    class ScopedContext
+      def initialize: (untyped ctx, String scope) -> void
+      def service_call: (untyped service, (String | Symbol) handler, untyped arg, ?key: String?, ?limit_key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
+      def service_send: (untyped service, (String | Symbol) handler, untyped arg, ?key: String?, ?delay: Numeric?, ?limit_key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
+      def object_call: (untyped service, (String | Symbol) handler, String key, untyped arg, ?limit_key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
+      def object_send: (untyped service, (String | Symbol) handler, String key, untyped arg, ?delay: Numeric?, ?limit_key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
+      def workflow_call: (untyped service, (String | Symbol) handler, String key, untyped arg, ?limit_key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
+      def workflow_send: (untyped service, (String | Symbol) handler, String key, untyped arg, ?delay: Numeric?, ?limit_key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
+    end
   end
 
   module JsonSerde

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restate-sdk
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Restate Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async