restate-sdk 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0916e5aeaaa8b06b50750be1b126fadecd9b26b63437fa8da07eaa66de351f5
-  data.tar.gz: 3723bd3f868ce6b8c9f05f3fe070b6f0ffaa3290130dd83baf83bd36390b716f
+  metadata.gz: bc7f07e2b3bd62dbf82cb815a5b66443586e339bb3ae896e6b94594fdce9fab4
+  data.tar.gz: 9066dc59318b6e14f249c249c59b03b8e075df6986cf2b2d8a3d9b93ca56614b
 SHA512:
-  metadata.gz: e8ff04264f631fa443395eb05493f30a6d88b0835e7df0aa1469ddc1e22ca4091cbd12d1f5a85d5dfef0339ed52b3db6664ccfc67e749de714fc4dffcddadcb7
-  data.tar.gz: bb01d499eb5a8cd9d2279343ff5d41a61bd7beddfca5c8db86864be4b5e989c83e24f20d33ab44f7e0021ea0fedb0a6861278ca2e8d028b3871c8e9eada81f29
+  metadata.gz: 79b2cee29852e255f9745665f44b8d4450badc22319c59120a2988c9ccd9dfa88723529ffb5059dbf4c94d929722368e00a5a1887c0e32b48663196513768860
+  data.tar.gz: 8faf5c53ca4b7bc538ff348a3ccb99a0cdbac8a418d9263073f67a8476353d8c01fb714784c93237f644b35ea7f1ff08e89074a1e07a2761f9c0d59f892643d5

data/Cargo.lock

@@ -569,7 +569,7 @@ dependencies = [
 
 [[package]]
 name = "restate_internal"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "magnus",
  "rb-sys",

data/ext/restate_internal/Cargo.toml

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

data/lib/restate/endpoint.rb

@@ -15,11 +15,15 @@ module Restate
     sig { returns(T.nilable(String)) }
     attr_accessor :protocol
 
+    sig { returns(T::Array[T.untyped]) }
+    attr_reader :middleware
+
     sig { void }
     def initialize
       @services = T.let({}, T::Hash[String, T.untyped])
       @protocol = T.let(nil, T.nilable(String))
       @identity_keys = T.let([], T::Array[String])
+      @middleware = T.let([], T::Array[T.untyped])
     end
 
     # Bind one or more services to this endpoint.
@@ -59,6 +63,70 @@ module Restate
       self
     end
 
+    # Add handler-level middleware.
+    #
+    # Middleware wraps every handler invocation with access to the handler metadata
+    # and context. Use it for tracing, metrics, logging, error reporting, etc.
+    #
+    # A middleware is a class whose instances respond to +call(handler, ctx)+.
+    # Use +yield+ inside +call+ to invoke the next middleware or the handler.
+    # The return value of +yield+ is the handler's return value.
+    #
+    # This follows the same pattern as {https://github.com/sidekiq/sidekiq/wiki/Middleware Sidekiq middleware}.
+    #
+    # @example OpenTelemetry tracing
+    #   class OpenTelemetryMiddleware
+    #     def call(handler, ctx)
+    #       tracer.in_span(handler.name, attributes: {
+    #         'restate.service' => handler.service_tag.name,
+    #         'restate.invocation_id' => ctx.request.id
+    #       }) do
+    #         yield
+    #       end
+    #     end
+    #   end
+    #   endpoint.use(OpenTelemetryMiddleware)
+    #
+    # @example Metrics
+    #   class MetricsMiddleware
+    #     def call(handler, ctx)
+    #       start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    #       result = yield
+    #       duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    #       StatsD.timing("restate.handler.#{handler.name}", duration)
+    #       result
+    #     end
+    #   end
+    #   endpoint.use(MetricsMiddleware)
+    #
+    # @example Middleware with configuration
+    #   class AuthMiddleware
+    #     def initialize(api_key:)
+    #       @api_key = api_key
+    #     end
+    #
+    #     def call(handler, ctx)
+    #       raise Restate::TerminalError.new('unauthorized', status_code: 401) unless valid?(ctx)
+    #       yield
+    #     end
+    #   end
+    #   endpoint.use(AuthMiddleware, api_key: 'secret')
+    #
+    # @param klass [Class] middleware class (will be instantiated by the SDK)
+    # @param args [Array] positional arguments for the middleware constructor
+    # @param kwargs [Hash] keyword arguments for the middleware constructor
+    # @return [self]
+    sig { params(klass: T.untyped, args: T.untyped, kwargs: T.untyped).returns(T.self_type) }
+    def use(klass, *args, **kwargs)
+      instance = if kwargs.empty?
+                   klass.new(*args)
+                 else
+                   klass.new(*args, **kwargs)
+                 end
+      @middleware << instance
+      self
+    end
+
     # Build and return the Rack-compatible application.
     sig { returns(T.untyped) }
     def app

data/lib/restate/handler.rb

@@ -33,19 +33,32 @@ module Restate
 
   # Invoke a handler with the context and raw input bytes.
   # The context is passed as the first argument to every handler.
+  # Middleware (if any) wraps the handler call.
   # Returns raw output bytes.
-  sig { params(handler: T.untyped, ctx: T.untyped, in_buffer: String).returns(String) }
-  def invoke_handler(handler:, ctx:, in_buffer:)
-    if handler.arity == 2
-      begin
-        in_arg = handler.handler_io.input_serde.deserialize(in_buffer)
-      rescue StandardError => e
-        Kernel.raise TerminalError, "Unable to parse input argument: #{e.message}"
+  sig do
+    params(handler: T.untyped, ctx: T.untyped, in_buffer: String,
+           middleware: T::Array[T.untyped]).returns(String)
+  end
+  def invoke_handler(handler:, ctx:, in_buffer:, middleware: []) # rubocop:disable Metrics/AbcSize
+    call_handler = Kernel.proc do
+      if handler.arity == 2
+        begin
+          in_arg = handler.handler_io.input_serde.deserialize(in_buffer)
+        rescue StandardError => e
+          Kernel.raise TerminalError, "Unable to parse input argument: #{e.message}"
+        end
+        handler.callable.call(ctx, in_arg)
+      else
+        handler.callable.call(ctx)
       end
-      out_arg = handler.callable.call(ctx, in_arg)
-    else
-      out_arg = handler.callable.call(ctx)
     end
+
+    # Build the middleware chain so each middleware can use `yield` to call the next.
+    chain = middleware.reverse.reduce(call_handler) do |nxt, mw|
+      Kernel.proc { mw.call(handler, ctx, &nxt) }
+    end
+
+    out_arg = chain.call
     handler.handler_io.output_serde.serialize(out_arg)
   end
 end

data/lib/restate/server.rb

@@ -204,7 +204,8 @@ module Restate
         handler: handler,
         invocation: invocation,
         send_output: send_output,
-        input_queue: input_queue
+        input_queue: input_queue,
+        middleware: @endpoint.middleware
       )
 
       # Spawn the handler as an async task so the response body can stream

data/lib/restate/server_context.rb

@@ -28,8 +28,11 @@ module Restate
     sig { returns(T.untyped) }
     attr_reader :invocation
 
-    sig { params(vm: VMWrapper, handler: T.untyped, invocation: T.untyped, send_output: T.untyped, input_queue: Async::Queue).void }
-    def initialize(vm:, handler:, invocation:, send_output:, input_queue:)
+    sig do
+      params(vm: VMWrapper, handler: T.untyped, invocation: T.untyped, send_output: T.untyped,
+             input_queue: Async::Queue, middleware: T::Array[T.untyped]).void
+    end
+    def initialize(vm:, handler:, invocation:, send_output:, input_queue:, middleware: [])
       @vm = T.let(vm, VMWrapper)
       @handler = T.let(handler, T.untyped)
       @invocation = T.let(invocation, T.untyped)
@@ -37,6 +40,7 @@ module Restate
       @input_queue = T.let(input_queue, Async::Queue)
       @run_coros_to_execute = T.let({}, T::Hash[Integer, T.untyped])
       @attempt_finished_event = T.let(AttemptFinishedEvent.new, AttemptFinishedEvent)
+      @middleware = T.let(middleware, T::Array[T.untyped])
     end
 
     # ── Main entry point ──
@@ -48,7 +52,8 @@ module Restate
       Thread.current[:restate_service_kind] = @handler.service_tag.kind
       Thread.current[:restate_handler_kind] = @handler.kind
       in_buffer = @invocation.input_buffer
-      out_buffer = Restate.invoke_handler(handler: @handler, ctx: self, in_buffer: in_buffer)
+      out_buffer = Restate.invoke_handler(handler: @handler, ctx: self, in_buffer: in_buffer,
+                                          middleware: @middleware)
       @vm.sys_write_output_success(out_buffer.b)
       @vm.sys_end
     rescue TerminalError => e

data/lib/restate/testing.rb

@@ -52,14 +52,17 @@ module Restate
       # @param restate_image [String] Docker image for Restate server.
       # @param always_replay [Boolean] Force replay on every suspension point.
       # @param disable_retries [Boolean] Disable Restate retry policy.
+      # @yield [Endpoint] Optional block to configure the endpoint (e.g. add middleware).
       def initialize(*services,
                      restate_image: 'docker.io/restatedev/restate:latest',
                      always_replay: false,
-                     disable_retries: false)
+                     disable_retries: false,
+                     &configure)
         @services = services
         @restate_image = restate_image
         @always_replay = always_replay
         @disable_retries = disable_retries
+        @configure = configure
         @server_thread = nil
         @container = nil
         @port = nil
@@ -69,7 +72,9 @@ module Restate
 
       def start
         @port = find_free_port
-        rack_app = Restate.endpoint(*@services).app
+        endpoint = Restate.endpoint(*@services)
+        @configure&.call(endpoint)
+        rack_app = endpoint.app
         start_sdk_server(rack_app)
         wait_for_tcp(@port)
         start_restate_container

data/lib/restate/version.rb

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

data/rbi/restate-sdk.rbi

@@ -0,0 +1,307 @@
+# typed: true
+
+# RBI shipped with the restate-sdk gem.
+# Tapioca merges this automatically when users run `tapioca gems`.
+
+module Restate
+  # Create an endpoint, optionally binding services.
+  sig do
+    params(
+      services: T.untyped,
+      protocol: T.nilable(String),
+      identity_keys: T.nilable(T::Array[String])
+    ).returns(Restate::Endpoint)
+  end
+  def self.endpoint(*services, protocol: nil, identity_keys: nil); end
+
+  # Returns the current context (any handler).
+  sig { returns(Restate::Context) }
+  def self.current_context; end
+
+  # Returns the current context for a VirtualObject exclusive handler.
+  sig { returns(Restate::ObjectContext) }
+  def self.current_object_context; end
+
+  # Returns the current context for a VirtualObject shared handler.
+  sig { returns(Restate::ObjectSharedContext) }
+  def self.current_shared_context; end
+
+  # Returns the current context for a Workflow main handler.
+  sig { returns(Restate::WorkflowContext) }
+  def self.current_workflow_context; end
+
+  # Returns the current context for a Workflow shared handler.
+  sig { returns(Restate::WorkflowSharedContext) }
+  def self.current_shared_workflow_context; end
+
+  class TerminalError < StandardError
+    sig { returns(Integer) }
+    def status_code; end
+
+    sig { params(message: String, status_code: Integer).void }
+    def initialize(message = '', status_code: 500); end
+  end
+
+  class AttemptFinishedEvent
+    sig { returns(T::Boolean) }
+    def set?; end
+
+    sig { void }
+    def wait; end
+  end
+
+  Request = T.type_alias { T.untyped }
+
+  class RunRetryPolicy < T::Struct
+    const :initial_interval, T.nilable(Integer)
+    const :max_attempts, T.nilable(Integer)
+    const :max_duration, T.nilable(Integer)
+    const :max_interval, T.nilable(Integer)
+    const :interval_factor, T.nilable(Float)
+  end
+
+  class DurableFuture
+    sig { returns(T.untyped) }
+    def await; end
+
+    sig { returns(T::Boolean) }
+    def completed?; end
+
+    sig { returns(Integer) }
+    def handle; end
+  end
+
+  class DurableCallFuture < DurableFuture
+    sig { returns(String) }
+    def invocation_id; end
+
+    sig { void }
+    def cancel; end
+  end
+
+  class SendHandle
+    sig { returns(String) }
+    def invocation_id; end
+
+    sig { void }
+    def cancel; end
+  end
+
+  # Base context interface for all Restate handlers.
+  module Context
+    sig do
+      params(
+        name: String, serde: T.untyped, retry_policy: T.nilable(RunRetryPolicy),
+        background: T::Boolean, action: T.proc.returns(T.untyped)
+      ).returns(DurableFuture)
+    end
+    def run(name, serde: Restate::JsonSerde, retry_policy: nil, background: false, &action); end
+
+    sig do
+      params(
+        name: String, serde: T.untyped, retry_policy: T.nilable(RunRetryPolicy),
+        background: T::Boolean, action: T.proc.returns(T.untyped)
+      ).returns(T.untyped)
+    end
+    def run_sync(name, serde: Restate::JsonSerde, retry_policy: nil, background: false, &action); end
+
+    sig { params(seconds: Numeric).returns(DurableFuture) }
+    def sleep(seconds); end
+
+    sig do
+      params(
+        service: T.any(String, T::Class[T.anything]), handler: T.any(String, Symbol),
+        arg: T.untyped, key: T.nilable(String), idempotency_key: T.nilable(String),
+        headers: T.nilable(T::Hash[String, String]), input_serde: T.untyped, output_serde: T.untyped
+      ).returns(DurableCallFuture)
+    end
+    def service_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil,
+                     input_serde: T.unsafe(nil), output_serde: T.unsafe(nil)); end
+
+    sig do
+      params(
+        service: T.any(String, T::Class[T.anything]), handler: T.any(String, Symbol),
+        arg: T.untyped, key: T.nilable(String), delay: T.nilable(Numeric),
+        idempotency_key: T.nilable(String), headers: T.nilable(T::Hash[String, String]),
+        input_serde: T.untyped
+      ).returns(SendHandle)
+    end
+    def service_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil,
+                     headers: nil, input_serde: T.unsafe(nil)); end
+
+    sig do
+      params(
+        service: T.any(String, T::Class[T.anything]), handler: T.any(String, Symbol),
+        key: String, arg: T.untyped, idempotency_key: T.nilable(String),
+        headers: T.nilable(T::Hash[String, String]), input_serde: T.untyped, output_serde: T.untyped
+      ).returns(DurableCallFuture)
+    end
+    def object_call(service, handler, key, arg, idempotency_key: nil, headers: nil,
+                    input_serde: T.unsafe(nil), output_serde: T.unsafe(nil)); end
+
+    sig do
+      params(
+        service: T.any(String, T::Class[T.anything]), handler: T.any(String, Symbol),
+        key: String, arg: T.untyped, delay: T.nilable(Numeric),
+        idempotency_key: T.nilable(String), headers: T.nilable(T::Hash[String, String]),
+        input_serde: T.untyped
+      ).returns(SendHandle)
+    end
+    def object_send(service, handler, key, arg, delay: nil, idempotency_key: nil,
+                    headers: nil, input_serde: T.unsafe(nil)); end
+
+    sig do
+      params(
+        service: T.any(String, T::Class[T.anything]), handler: T.any(String, Symbol),
+        key: String, arg: T.untyped, idempotency_key: T.nilable(String),
+        headers: T.nilable(T::Hash[String, String]), input_serde: T.untyped, output_serde: T.untyped
+      ).returns(DurableCallFuture)
+    end
+    def workflow_call(service, handler, key, arg, idempotency_key: nil, headers: nil,
+                      input_serde: T.unsafe(nil), output_serde: T.unsafe(nil)); end
+
+    sig do
+      params(
+        service: T.any(String, T::Class[T.anything]), handler: T.any(String, Symbol),
+        key: String, arg: T.untyped, delay: T.nilable(Numeric),
+        idempotency_key: T.nilable(String), headers: T.nilable(T::Hash[String, String]),
+        input_serde: T.untyped
+      ).returns(SendHandle)
+    end
+    def workflow_send(service, handler, key, arg, delay: nil, idempotency_key: nil,
+                      headers: nil, input_serde: T.unsafe(nil)); end
+
+    sig do
+      params(
+        service: String, handler: String, arg: String,
+        key: T.nilable(String), idempotency_key: T.nilable(String),
+        headers: T.nilable(T::Hash[String, String])
+      ).returns(DurableCallFuture)
+    end
+    def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil); end
+
+    sig do
+      params(
+        service: String, handler: String, arg: String,
+        key: T.nilable(String), delay: T.nilable(Numeric),
+        idempotency_key: T.nilable(String), headers: T.nilable(T::Hash[String, String])
+      ).returns(SendHandle)
+    end
+    def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil); end
+
+    sig { params(serde: T.untyped).returns([String, DurableFuture]) }
+    def awakeable(serde: Restate::JsonSerde); end
+
+    sig { params(awakeable_id: String, payload: T.untyped, serde: T.untyped).void }
+    def resolve_awakeable(awakeable_id, payload, serde: Restate::JsonSerde); end
+
+    sig { params(awakeable_id: String, message: String, code: Integer).void }
+    def reject_awakeable(awakeable_id, message, code: 500); end
+
+    sig { params(invocation_id: String).void }
+    def cancel_invocation(invocation_id); end
+
+    sig { params(futures: DurableFuture).returns([T::Array[DurableFuture], T::Array[DurableFuture]]) }
+    def wait_any(*futures); end
+
+    sig { returns(T.untyped) }
+    def request; end
+
+    sig { returns(String) }
+    def key; end
+  end
+
+  # VirtualObject shared handler context (read-only state).
+  module ObjectSharedContext
+    include Context
+
+    sig { params(name: String, serde: T.untyped).returns(T.untyped) }
+    def get(name, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, serde: T.untyped).returns(DurableFuture) }
+    def get_async(name, serde: Restate::JsonSerde); end
+
+    sig { returns(T.untyped) }
+    def state_keys; end
+
+    sig { returns(DurableFuture) }
+    def state_keys_async; end
+  end
+
+  # VirtualObject exclusive handler context (full state access).
+  module ObjectContext
+    include ObjectSharedContext
+
+    sig { params(name: String, value: T.untyped, serde: T.untyped).void }
+    def set(name, value, serde: Restate::JsonSerde); end
+
+    sig { params(name: String).void }
+    def clear(name); end
+
+    sig { void }
+    def clear_all; end
+  end
+
+  # Workflow shared handler context (read-only state + promises).
+  module WorkflowSharedContext
+    include ObjectSharedContext
+
+    sig { params(name: String, serde: T.untyped).returns(T.untyped) }
+    def promise(name, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, serde: T.untyped).returns(T.untyped) }
+    def peek_promise(name, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, payload: T.untyped, serde: T.untyped).void }
+    def resolve_promise(name, payload, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, message: String, code: Integer).void }
+    def reject_promise(name, message, code: 500); end
+  end
+
+  # Workflow main handler context (full state + promises).
+  module WorkflowContext
+    include ObjectContext
+
+    sig { params(name: String, serde: T.untyped).returns(T.untyped) }
+    def promise(name, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, serde: T.untyped).returns(T.untyped) }
+    def peek_promise(name, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, payload: T.untyped, serde: T.untyped).void }
+    def resolve_promise(name, payload, serde: Restate::JsonSerde); end
+
+    sig { params(name: String, message: String, code: Integer).void }
+    def reject_promise(name, message, code: 500); end
+  end
+
+  # Stateless service base class.
+  class Service; end
+
+  # Keyed virtual object base class.
+  class VirtualObject; end
+
+  # Durable workflow base class.
+  class Workflow; end
+
+  class Endpoint
+    sig { params(services: T.untyped).void }
+    def bind(*services); end
+
+    sig { void }
+    def streaming_protocol; end
+
+    sig { void }
+    def request_response_protocol; end
+
+    sig { params(key: String).void }
+    def identity_key(key); end
+
+    sig { returns(T.untyped) }
+    def app; end
+  end
+
+  module JsonSerde; end
+  module BytesSerde; end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restate-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Restate Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -86,6 +86,7 @@ files:
 - lib/restate/vm.rb
 - lib/restate/workflow.rb
 - lib/tapioca/dsl/compilers/restate.rb
+- rbi/restate-sdk.rbi
 homepage: https://github.com/restatedev/sdk-ruby
 licenses:
 - MIT