restate-sdk 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b23261e2b75927f25f70d83c93133191b894a2451c8a194e73a38e91b3f44d6
-  data.tar.gz: 269ac3b7c8a496da0db88b53d5dedbd54afe64a6507c712c9d71c828811bfb55
+  metadata.gz: bc7f07e2b3bd62dbf82cb815a5b66443586e339bb3ae896e6b94594fdce9fab4
+  data.tar.gz: 9066dc59318b6e14f249c249c59b03b8e075df6986cf2b2d8a3d9b93ca56614b
 SHA512:
-  metadata.gz: 3b66009141e9bfba8841a5f73c7a8bd4b808d36f1edd122f70e73b91f4718f5a0de1f8d653c55b1686839c66dbef802a1f71a13e7fba71fbb4d631b2c1721295
-  data.tar.gz: 9caa27f5058be3d18cf9a06295dc828c5053cbb3d4622c6944ec6f27466b8b80e41b67e11ac244c3fb1847297e24b03997aec7fe602347bdabfa9377213b77d9
+  metadata.gz: 79b2cee29852e255f9745665f44b8d4450badc22319c59120a2988c9ccd9dfa88723529ffb5059dbf4c94d929722368e00a5a1887c0e32b48663196513768860
+  data.tar.gz: 8faf5c53ca4b7bc538ff348a3ccb99a0cdbac8a418d9263073f67a8476353d8c01fb714784c93237f644b35ea7f1ff08e89074a1e07a2761f9c0d59f892643d5

data/Cargo.lock

@@ -569,7 +569,7 @@ dependencies = [
 
 [[package]]
 name = "restate_internal"
-version = "0.5.1"
+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.1"
+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.1'
+  VERSION = '0.6.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restate-sdk
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  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