restate-sdk 0.11.0 → 0.13.0

data/lib/restate/server/handler.rb

@@ -0,0 +1,269 @@
+# typed: ignore
+# frozen_string_literal: true
+
+require 'async'
+require 'async/queue'
+require 'logger'
+require_relative 'context'
+
+module Restate
+  module Server
+    # Rack-compatible application that handles Restate protocol requests.
+    # Designed to work with Falcon for HTTP/2 bidirectional streaming.
+    #
+    # Routes:
+    #   GET  /discover                     → service manifest
+    #   GET  /health                       → health check
+    #   POST /invoke/:service/:handler     → handler invocation
+    class Handler
+      SDK_VERSION = Internal::SDK_VERSION
+      X_RESTATE_SERVER = "restate-sdk-ruby/#{SDK_VERSION}".freeze
+
+      LOGGER = Logger.new($stdout, progname: 'Restate::Server::Handler')
+
+      def initialize(endpoint)
+        @endpoint = endpoint
+        @identity_verifier = Internal::IdentityVerifier.new(endpoint.identity_keys)
+      end
+
+      # Rack interface
+      def call(env)
+        path = env['PATH_INFO'] || '/'
+        parsed = parse_path(path)
+
+        case parsed[:type]
+        when :health
+          health_response
+        when :discover
+          handle_discover(env)
+        when :invocation
+          handle_invocation(env, parsed[:service], parsed[:handler])
+        else
+          not_found_response
+        end
+      rescue StandardError => e
+        LOGGER.error("Exception in Restate server: #{e.inspect}")
+        LOGGER.error(e.backtrace&.join("\n")) if e.backtrace
+        error_response(500, 'Internal server error')
+      end
+
+      private
+
+      def parse_path(path)
+        segments = path.split('/').reject(&:empty?)
+
+        # Check for /invoke/:service/:handler
+        if segments.length >= 3
+          invoke_idx = segments.rindex('invoke')
+          if invoke_idx && segments.length > invoke_idx + 2
+            return {
+              type: :invocation,
+              service: segments[invoke_idx + 1],
+              handler: segments[invoke_idx + 2]
+            }
+          end
+        end
+
+        case segments.last
+        when 'health'
+          { type: :health }
+        when 'discover'
+          { type: :discover }
+        else
+          { type: :unknown }
+        end
+      end
+
+      def health_response
+        [200, { 'content-type' => 'application/json', 'x-restate-server' => X_RESTATE_SERVER }, ['{"status":"ok"}']]
+      end
+
+      def not_found_response
+        [404, { 'x-restate-server' => X_RESTATE_SERVER }, ['']]
+      end
+
+      def error_response(status, message)
+        [status, { 'content-type' => 'text/plain', 'x-restate-server' => X_RESTATE_SERVER }, [message]]
+      end
+
+      def handle_discover(env)
+        # Detect HTTP version for protocol mode
+        http_version = env['HTTP_VERSION'] || env['SERVER_PROTOCOL'] || 'HTTP/1.1'
+        discovered_as = http_version.include?('2') ? 'bidi' : 'request_response'
+
+        # Negotiate discovery protocol version from Accept header
+        accept = env['HTTP_ACCEPT'] || ''
+        version = negotiate_version(accept)
+        return error_response(415, "Unsupported discovery version: #{accept}") unless version
+
+        begin
+          json = Discovery.compute_discovery_json(@endpoint, version, discovered_as)
+          content_type = "application/vnd.restate.endpointmanifest.v#{version}+json"
+          [
+            200,
+            {
+              'content-type' => content_type,
+              'x-restate-server' => X_RESTATE_SERVER
+            },
+            [json]
+          ]
+        rescue StandardError => e
+          error_response(500, "Error computing discovery: #{e.message}")
+        end
+      end
+
+      def negotiate_version(accept)
+        if accept.include?('application/vnd.restate.endpointmanifest.v4+json')
+          4
+        elsif accept.include?('application/vnd.restate.endpointmanifest.v3+json')
+          3
+        elsif accept.include?('application/vnd.restate.endpointmanifest.v2+json')
+          2
+        elsif accept.empty?
+          2
+        end
+      end
+
+      def handle_invocation(env, service_name, handler_name)
+        # Verify identity
+        request_headers = extract_headers(env)
+        path = env['PATH_INFO'] || '/'
+        begin
+          @identity_verifier.verify(request_headers, path)
+        rescue Internal::IdentityVerificationError
+          return [401, { 'x-restate-server' => X_RESTATE_SERVER }, ['']]
+        end
+
+        # Find the service and handler
+        service = @endpoint.services[service_name]
+        return not_found_response unless service
+
+        handler = service.handlers[handler_name]
+        return not_found_response unless handler
+
+        # Process the invocation with streaming
+        process_invocation(env, handler, request_headers)
+      end
+
+      def process_invocation(env, handler, request_headers)
+        vm = VMWrapper.new(request_headers)
+        status, response_headers = vm.get_response_head
+
+        # Streaming response body — output chunks are sent to Restate as they're
+        # produced. This is critical for BidiStream mode where the VM needs output
+        # acknowledged before it can make further progress.
+        output_queue = Async::Queue.new
+        send_output = ->(chunk) { output_queue.enqueue(chunk) }
+
+        # Input queue bridges the HTTP body reader and the handler's progress loop.
+        input_queue = Async::Queue.new
+
+        # Read request body chunks and feed to VM until ready to execute,
+        # then continue feeding remaining chunks via the input queue.
+        rack_input = env['rack.input']
+        ready = false
+        if rack_input
+          # Feed chunks until the VM has enough to start execution
+          while (chunk = rack_input.read_partial(16_384))
+            vm.notify_input(chunk.b) unless chunk.empty?
+            if vm.is_ready_to_execute
+              ready = true
+              break
+            end
+          end
+          vm.notify_input_closed unless ready
+        end
+
+        invocation = vm.sys_input
+
+        # Spawn a background task to continue reading remaining input
+        if ready
+          Async do
+            while (chunk = rack_input.read_partial(16_384))
+              input_queue.enqueue(chunk.b) unless chunk.empty?
+            end
+            input_queue.enqueue(:eof)
+          rescue StandardError => e
+            LOGGER.error("Input reader error: #{e.inspect}")
+            input_queue.enqueue(:disconnected)
+          end
+        end
+
+        context = Context.new(
+          vm: vm,
+          handler: handler,
+          invocation: invocation,
+          send_output: send_output,
+          input_queue: input_queue,
+          middleware: @endpoint.middleware,
+          outbound_middleware: @endpoint.outbound_middleware
+        )
+
+        # Spawn the handler as an async task so the response body can stream
+        # output concurrently.
+        Async do
+          begin
+            context.enter
+          rescue DisconnectedError
+            # Client disconnected
+          rescue StandardError => e
+            LOGGER.error("Exception in handler: #{e.inspect}")
+          ensure
+            # Signal that the attempt is finished — wakes any waiters on
+            # ctx.request.attempt_finished_event and cancels pending background pool jobs.
+            context.on_attempt_finished
+          end
+
+          # Drain remaining output from VM
+          loop do
+            chunk = vm.take_output
+            break if chunk.nil? || chunk.empty?
+
+            output_queue.enqueue(chunk)
+          end
+
+          # Signal end of output
+          output_queue.enqueue(nil)
+        end
+
+        body = StreamingBody.new(output_queue)
+
+        merged_headers = response_headers.to_h { |pair| [pair[0], pair[1]] }
+        merged_headers['x-restate-server'] = X_RESTATE_SERVER
+
+        [status, merged_headers, body]
+      end
+
+      # Rack 3 streaming body that yields chunks from an Async::Queue.
+      # Terminates when nil is dequeued.
+      class StreamingBody
+        def initialize(queue)
+          @queue = queue
+        end
+
+        def each
+          loop do
+            chunk = @queue.dequeue
+            break if chunk.nil?
+
+            yield chunk
+          end
+        end
+      end
+
+      def extract_headers(env)
+        headers = []
+        env.each do |key, value|
+          next unless key.start_with?('HTTP_')
+
+          header_name = key.byteslice(5..).tr('_', '-').downcase!
+          headers << [header_name, value]
+        end
+        # Also include content-type and content-length if present
+        headers << ['content-type', env['CONTENT_TYPE']] if env['CONTENT_TYPE']
+        headers << ['content-length', env['CONTENT_LENGTH']] if env['CONTENT_LENGTH']
+        headers
+      end
+    end
+  end
+end

data/lib/restate/server.rb

@@ -1,266 +1,9 @@
-# typed: ignore
 # frozen_string_literal: true
 
-require 'async'
-require 'async/queue'
-require 'logger'
-
-module Restate
-  # Rack-compatible application that handles Restate protocol requests.
-  # Designed to work with Falcon for HTTP/2 bidirectional streaming.
-  #
-  # Routes:
-  #   GET  /discover                     → service manifest
-  #   GET  /health                       → health check
-  #   POST /invoke/:service/:handler     → handler invocation
-  class Server
-    SDK_VERSION = Internal::SDK_VERSION
-    X_RESTATE_SERVER = "restate-sdk-ruby/#{SDK_VERSION}".freeze
-
-    LOGGER = Logger.new($stdout, progname: 'Restate::Server')
-
-    def initialize(endpoint)
-      @endpoint = endpoint
-      @identity_verifier = Internal::IdentityVerifier.new(endpoint.identity_keys)
-    end
-
-    # Rack interface
-    def call(env)
-      path = env['PATH_INFO'] || '/'
-      parsed = parse_path(path)
-
-      case parsed[:type]
-      when :health
-        health_response
-      when :discover
-        handle_discover(env)
-      when :invocation
-        handle_invocation(env, parsed[:service], parsed[:handler])
-      else
-        not_found_response
-      end
-    rescue StandardError => e
-      LOGGER.error("Exception in Restate server: #{e.inspect}")
-      LOGGER.error(e.backtrace&.join("\n")) if e.backtrace
-      error_response(500, 'Internal server error')
-    end
-
-    private
-
-    def parse_path(path)
-      segments = path.split('/').reject(&:empty?)
-
-      # Check for /invoke/:service/:handler
-      if segments.length >= 3
-        invoke_idx = segments.rindex('invoke')
-        if invoke_idx && segments.length > invoke_idx + 2
-          return {
-            type: :invocation,
-            service: segments[invoke_idx + 1],
-            handler: segments[invoke_idx + 2]
-          }
-        end
-      end
-
-      case segments.last
-      when 'health'
-        { type: :health }
-      when 'discover'
-        { type: :discover }
-      else
-        { type: :unknown }
-      end
-    end
-
-    def health_response
-      [200, { 'content-type' => 'application/json', 'x-restate-server' => X_RESTATE_SERVER }, ['{"status":"ok"}']]
-    end
-
-    def not_found_response
-      [404, { 'x-restate-server' => X_RESTATE_SERVER }, ['']]
-    end
-
-    def error_response(status, message)
-      [status, { 'content-type' => 'text/plain', 'x-restate-server' => X_RESTATE_SERVER }, [message]]
-    end
-
-    def handle_discover(env)
-      # Detect HTTP version for protocol mode
-      http_version = env['HTTP_VERSION'] || env['SERVER_PROTOCOL'] || 'HTTP/1.1'
-      discovered_as = http_version.include?('2') ? 'bidi' : 'request_response'
-
-      # Negotiate discovery protocol version from Accept header
-      accept = env['HTTP_ACCEPT'] || ''
-      version = negotiate_version(accept)
-      return error_response(415, "Unsupported discovery version: #{accept}") unless version
-
-      begin
-        json = Discovery.compute_discovery_json(@endpoint, version, discovered_as)
-        content_type = "application/vnd.restate.endpointmanifest.v#{version}+json"
-        [
-          200,
-          {
-            'content-type' => content_type,
-            'x-restate-server' => X_RESTATE_SERVER
-          },
-          [json]
-        ]
-      rescue StandardError => e
-        error_response(500, "Error computing discovery: #{e.message}")
-      end
-    end
-
-    def negotiate_version(accept)
-      if accept.include?('application/vnd.restate.endpointmanifest.v4+json')
-        4
-      elsif accept.include?('application/vnd.restate.endpointmanifest.v3+json')
-        3
-      elsif accept.include?('application/vnd.restate.endpointmanifest.v2+json')
-        2
-      elsif accept.empty?
-        2
-      end
-    end
-
-    def handle_invocation(env, service_name, handler_name)
-      # Verify identity
-      request_headers = extract_headers(env)
-      path = env['PATH_INFO'] || '/'
-      begin
-        @identity_verifier.verify(request_headers, path)
-      rescue Internal::IdentityVerificationError
-        return [401, { 'x-restate-server' => X_RESTATE_SERVER }, ['']]
-      end
-
-      # Find the service and handler
-      service = @endpoint.services[service_name]
-      return not_found_response unless service
-
-      handler = service.handlers[handler_name]
-      return not_found_response unless handler
-
-      # Process the invocation with streaming
-      process_invocation(env, handler, request_headers)
-    end
-
-    def process_invocation(env, handler, request_headers)
-      vm = VMWrapper.new(request_headers)
-      status, response_headers = vm.get_response_head
-
-      # Streaming response body — output chunks are sent to Restate as they're
-      # produced. This is critical for BidiStream mode where the VM needs output
-      # acknowledged before it can make further progress.
-      output_queue = Async::Queue.new
-      send_output = ->(chunk) { output_queue.enqueue(chunk) }
-
-      # Input queue bridges the HTTP body reader and the handler's progress loop.
-      input_queue = Async::Queue.new
-
-      # Read request body chunks and feed to VM until ready to execute,
-      # then continue feeding remaining chunks via the input queue.
-      rack_input = env['rack.input']
-      ready = false
-      if rack_input
-        # Feed chunks until the VM has enough to start execution
-        while (chunk = rack_input.read_partial(16_384))
-          vm.notify_input(chunk.b) unless chunk.empty?
-          if vm.is_ready_to_execute
-            ready = true
-            break
-          end
-        end
-        vm.notify_input_closed unless ready
-      end
-
-      invocation = vm.sys_input
-
-      # Spawn a background task to continue reading remaining input
-      if ready
-        Async do
-          while (chunk = rack_input.read_partial(16_384))
-            input_queue.enqueue(chunk.b) unless chunk.empty?
-          end
-          input_queue.enqueue(:eof)
-        rescue StandardError => e
-          LOGGER.error("Input reader error: #{e.inspect}")
-          input_queue.enqueue(:disconnected)
-        end
-      end
-
-      context = ServerContext.new(
-        vm: vm,
-        handler: handler,
-        invocation: invocation,
-        send_output: send_output,
-        input_queue: input_queue,
-        middleware: @endpoint.middleware,
-        outbound_middleware: @endpoint.outbound_middleware
-      )
-
-      # Spawn the handler as an async task so the response body can stream
-      # output concurrently.
-      Async do
-        begin
-          context.enter
-        rescue DisconnectedError
-          # Client disconnected
-        rescue StandardError => e
-          LOGGER.error("Exception in handler: #{e.inspect}")
-        ensure
-          # Signal that the attempt is finished — wakes any waiters on
-          # ctx.request.attempt_finished_event and cancels pending background pool jobs.
-          context.on_attempt_finished
-        end
-
-        # Drain remaining output from VM
-        loop do
-          chunk = vm.take_output
-          break if chunk.nil? || chunk.empty?
-
-          output_queue.enqueue(chunk)
-        end
-
-        # Signal end of output
-        output_queue.enqueue(nil)
-      end
-
-      body = StreamingBody.new(output_queue)
-
-      merged_headers = response_headers.to_h { |pair| [pair[0], pair[1]] }
-      merged_headers['x-restate-server'] = X_RESTATE_SERVER
-
-      [status, merged_headers, body]
-    end
-
-    # Rack 3 streaming body that yields chunks from an Async::Queue.
-    # Terminates when nil is dequeued.
-    class StreamingBody
-      def initialize(queue)
-        @queue = queue
-      end
-
-      def each
-        loop do
-          chunk = @queue.dequeue
-          break if chunk.nil?
-
-          yield chunk
-        end
-      end
-    end
-
-    def extract_headers(env)
-      headers = []
-      env.each do |key, value|
-        next unless key.start_with?('HTTP_')
-
-        header_name = key.byteslice(5..).tr('_', '-').downcase!
-        headers << [header_name, value]
-      end
-      # Also include content-type and content-length if present
-      headers << ['content-type', env['CONTENT_TYPE']] if env['CONTENT_TYPE']
-      headers << ['content-length', env['CONTENT_LENGTH']] if env['CONTENT_LENGTH']
-      headers
-    end
-  end
-end
+# Convenience entry point: `require "restate/server"` loads the core SDK
+# plus the server module (Rack app + async execution context).
+#
+# Use this when you want both core and server loaded eagerly, e.g.:
+#   gem "restate-sdk", require: "restate/server"
+require_relative '../restate'
+require_relative 'server/handler'

data/lib/restate/version.rb

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

data/lib/restate/vm.rb

@@ -7,14 +7,19 @@ begin
   RUBY_VERSION =~ /(\d+\.\d+)/
   require_relative "#{Regexp.last_match(1)}/restate_internal"
 rescue LoadError
-  # Fall back to the default location (development builds, source gem installs)
-  require_relative 'restate_internal'
+  begin
+    # rake compile output (ext.lib_dir = 'lib/restate' in Rakefile)
+    require_relative 'restate_internal'
+  rescue LoadError
+    # gem install from source: extconf.rb builds to lib/restate_internal
+    require_relative '../restate_internal'
+  end
 end
 
 module Restate
   # Ruby-side data types for VM results
   Invocation = Struct.new(:invocation_id, :random_seed, :headers, :input_buffer, :key, keyword_init: true)
-  Failure = Struct.new(:code, :message, :stacktrace, keyword_init: true)
+  Failure = Struct.new(:code, :message, :stacktrace, :metadata, keyword_init: true)
 
   class NotReady; end
   class Suspended; end
@@ -157,12 +162,12 @@ module Restate
     end
 
     def propose_run_completion_failure(handle, failure)
-      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil, native_metadata(failure))
       @vm.propose_run_completion_failure(handle, native_failure)
     end
 
     def propose_run_completion_transient(handle, failure:, attempt_duration_ms:, config:)
-      native_failure = Internal::Failure.new(failure.code, failure.message, failure.stacktrace)
+      native_failure = Internal::Failure.new(failure.code, failure.message, failure.stacktrace, nil)
       native_config = Internal::ExponentialRetryConfig.new(
         config.initial_interval, config.max_attempts,
         config.max_duration, config.max_interval,
@@ -176,7 +181,7 @@ module Restate
     end
 
     def sys_write_output_failure(failure)
-      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil, native_metadata(failure))
       @vm.sys_write_output_failure(native_failure)
     end
 
@@ -198,7 +203,7 @@ module Restate
     end
 
     def sys_complete_awakeable_failure(awakeable_id, failure)
-      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil, native_metadata(failure))
       @vm.sys_complete_awakeable_failure(awakeable_id, native_failure)
     end
 
@@ -215,7 +220,7 @@ module Restate
     end
 
     def sys_complete_promise_failure(key, failure)
-      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil, native_metadata(failure))
       @vm.sys_complete_promise_failure(key, native_failure)
     end
 
@@ -232,12 +237,19 @@ module Restate
     end
 
     def sys_complete_signal_failure(invocation_id, name, failure)
-      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil, native_metadata(failure))
       @vm.sys_complete_signal_failure(invocation_id, name, native_failure)
     end
 
     private
 
+    def native_metadata(failure)
+      md = failure.metadata
+      return nil if md.nil? || md.empty?
+
+      md.map { |k, v| [k.to_s, v.to_s] }
+    end
+
     def map_do_progress(result)
       case result
       when Internal::Suspended
@@ -270,7 +282,7 @@ module Restate
         # The native layer returns RString for both.
         result
       when Internal::Failure
-        Failure.new(code: result.code, message: result.message)
+        Failure.new(code: result.code, message: result.message, metadata: result.metadata.to_h)
       when Internal::StateKeys
         result.keys
       else

data/lib/restate.rb

@@ -11,7 +11,6 @@ require_relative 'restate/service_dsl'
 require_relative 'restate/service'
 require_relative 'restate/virtual_object'
 require_relative 'restate/workflow'
-require_relative 'restate/server_context'
 require_relative 'restate/durable_future'
 require_relative 'restate/discovery'
 require_relative 'restate/endpoint'
@@ -77,7 +76,13 @@ module Restate # rubocop:disable Metrics/ModuleLength
   def client
     cfg = config
     Client.new(ingress_url: cfg.ingress_url, admin_url: cfg.admin_url,
-               ingress_headers: cfg.ingress_headers, admin_headers: cfg.admin_headers)
+               ingress_headers: resolve_headers(cfg.ingress_headers),
+               admin_headers: resolve_headers(cfg.admin_headers))
+  end
+
+  # @!visibility private
+  def resolve_headers(headers)
+    headers.respond_to?(:call) ? headers.call : headers
   end
 
   # ── Context accessor (internal) ──

data/sig/restate.rbs

@@ -69,7 +69,8 @@ module Restate
 
   class TerminalError < StandardError
     attr_reader status_code: Integer
-    def initialize: (?String message, ?status_code: Integer) -> void
+    attr_reader metadata: Hash[String, String]?
+    def initialize: (?String message, ?status_code: Integer, ?metadata: Hash[String, String]?) -> void
   end
 
   class SuspendedError < StandardError
@@ -185,8 +186,14 @@ module Restate
 
   # ── Internal ──
 
-  class Server
-    def initialize: (untyped endpoint) -> void
+  module Server
+    class Handler
+      def initialize: (untyped endpoint) -> void
+      def call: (Hash[String, untyped] env) -> [Integer, Hash[String, String], untyped]
+    end
+
+    class Context
+    end
   end
 
   module JsonSerde