restate-sdk 0.4.3

data/lib/restate/errors.rb

@@ -0,0 +1,60 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Restate
+  # Raised to indicate a non-retryable failure. Restate will not retry the invocation.
+  #
+  # @example
+  #   raise Restate::TerminalError.new('not found', status_code: 404)
+  class TerminalError < StandardError
+    extend T::Sig
+
+    sig { returns(Integer) }
+    attr_reader :status_code
+
+    sig { params(message: String, status_code: Integer).void }
+    def initialize(message = 'Internal Server Error', status_code: 500)
+      super(message)
+      @status_code = T.let(status_code, Integer)
+    end
+  end
+
+  # Internal: raised when the VM suspends execution.
+  # User code should NOT catch this.
+  class SuspendedError < StandardError
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      super(
+        "Invocation got suspended, Restate will resume this invocation when progress can be made.\n" \
+        "This exception is safe to ignore. If you see it, you might be using a bare rescue.\n\n" \
+        "Don't do:\nbegin\n  # Code\nrescue => e\n  # This catches SuspendedError!\nend\n\n" \
+        "Do instead:\nbegin\n  # Code\nrescue Restate::TerminalError => e\n  # Handle terminal errors\nend"
+      )
+    end
+  end
+
+  # Internal: raised when the VM encounters a retryable error.
+  class InternalError < StandardError
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      super(
+        "Invocation attempt raised a retryable error.\n" \
+        'Restate will retry executing this invocation from the point where it left off.'
+      )
+    end
+  end
+
+  # Internal: raised when the HTTP connection is lost.
+  class DisconnectedError < StandardError
+    extend T::Sig
+
+    sig { void }
+    def initialize
+      super('Disconnected. The connection to the restate server was lost. Restate will retry the attempt.')
+    end
+  end
+end

data/lib/restate/handler.rb

@@ -0,0 +1,51 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # Identifies which service a handler belongs to.
+  ServiceTag = Struct.new(:kind, :name, :description, :metadata, keyword_init: true)
+
+  # Describes the input/output serialization for a handler.
+  # Schema is accessed via the serde's json_schema method.
+  HandlerIO = Struct.new(:accept, :content_type, :input_serde, :output_serde, keyword_init: true) do
+    def initialize(accept: 'application/json', content_type: 'application/json',
+                   input_serde: JsonSerde, output_serde: JsonSerde)
+      super
+    end
+  end
+
+  # A registered handler with its metadata and callable block.
+  Handler = Struct.new(
+    :service_tag, :handler_io, :kind, :name, :callable, :arity,
+    :enable_lazy_state,
+    :description, :metadata,
+    :inactivity_timeout, :abort_timeout,
+    :journal_retention, :idempotency_retention,
+    :workflow_completion_retention,
+    :ingress_private,
+    :invocation_retry_policy,
+    keyword_init: true
+  )
+
+  extend T::Sig
+
+  module_function
+
+  # Invoke a handler with raw input bytes. The context is available via
+  # fiber-local Restate.current_context (set by ServerContext#enter).
+  # Returns raw output bytes.
+  sig { params(handler: T.untyped, in_buffer: String).returns(String) }
+  def invoke_handler(handler:, in_buffer:)
+    if handler.arity == 1
+      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
+      out_arg = handler.callable.call(in_arg)
+    else
+      out_arg = handler.callable.call
+    end
+    handler.handler_io.output_serde.serialize(out_arg)
+  end
+end

data/lib/restate/serde.rb

@@ -0,0 +1,313 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'json'
+
+module Restate
+  # JSON serializer/deserializer (default).
+  # Converts Ruby objects to JSON byte strings and back.
+  module JsonSerde
+    extend T::Sig
+
+    module_function
+
+    # Serialize a Ruby object to a JSON byte string. Returns empty bytes for nil.
+    sig { params(obj: T.untyped).returns(String) }
+    def serialize(obj)
+      return ''.b if obj.nil?
+
+      JSON.generate(obj).b
+    end
+
+    # Deserialize a JSON byte string to a Ruby object. Returns nil for nil or empty input.
+    sig { params(buf: T.nilable(String)).returns(T.untyped) }
+    def deserialize(buf)
+      return nil if buf.nil? || buf.empty?
+
+      JSON.parse(buf, symbolize_names: false)
+    end
+
+    # Return the JSON Schema for this serde, or nil if unspecified.
+    sig { returns(T.nilable(T::Hash[String, T.untyped])) }
+    def json_schema
+      nil
+    end
+  end
+
+  # Sentinel value to distinguish "caller didn't pass serde" from an explicit value.
+  NOT_SET = Object.new.freeze
+
+  # Pass-through bytes serializer/deserializer.
+  # Passes binary data through without transformation.
+  module BytesSerde
+    extend T::Sig
+
+    module_function
+
+    # Serialize an object by returning its binary encoding. Returns empty bytes for nil.
+    sig { params(obj: T.untyped).returns(String) }
+    def serialize(obj)
+      return ''.b if obj.nil?
+
+      obj.b
+    end
+
+    # Deserialize by returning the raw buffer unchanged.
+    sig { params(buf: T.nilable(String)).returns(T.nilable(String)) }
+    def deserialize(buf)
+      buf
+    end
+
+    # Return the JSON Schema for this serde, or nil if unspecified.
+    sig { returns(T.nilable(T::Hash[String, T.untyped])) }
+    def json_schema
+      nil
+    end
+  end
+
+  # Maps Ruby primitive types to JSON Schema snippets for discovery.
+  PRIMITIVE_SCHEMAS = {
+    String => { 'type' => 'string' },
+    Integer => { 'type' => 'integer' },
+    Float => { 'type' => 'number' },
+    TrueClass => { 'type' => 'boolean' },
+    FalseClass => { 'type' => 'boolean' },
+    Array => { 'type' => 'array' },
+    Hash => { 'type' => 'object' },
+    NilClass => { 'type' => 'null' }
+  }.freeze
+
+  # Serde resolution utilities: converts a type or serde into a serde object.
+  module Serde
+    extend T::Sig
+
+    module_function
+
+    # Check if an object quacks like a serde (has serialize + deserialize).
+    sig { params(obj: T.untyped).returns(T::Boolean) }
+    def serde?(obj)
+      obj.respond_to?(:serialize) && obj.respond_to?(:deserialize)
+    end
+
+    # Resolve a type or serde into a serde object with serialize/deserialize/json_schema.
+    sig { params(type_or_serde: T.untyped).returns(T.untyped) }
+    def resolve(type_or_serde)
+      return JsonSerde if type_or_serde.nil?
+      return type_or_serde if serde?(type_or_serde)
+      return TStructSerde.new(type_or_serde) if t_struct?(type_or_serde)
+      return DryStructSerde.new(type_or_serde) if dry_struct?(type_or_serde)
+      return TypeSerde.new(type_or_serde, PRIMITIVE_SCHEMAS[type_or_serde]) if PRIMITIVE_SCHEMAS.key?(type_or_serde)
+      return TypeSerde.new(type_or_serde, type_or_serde.json_schema) if type_or_serde.respond_to?(:json_schema)
+
+      JsonSerde
+    end
+
+    # Check if a value is a T::Struct subclass.
+    sig { params(val: T.untyped).returns(T::Boolean) }
+    def t_struct?(val)
+      !!(val.is_a?(Class) && val < T::Struct)
+    end
+
+    # Check if a value is a Dry::Struct subclass.
+    sig { params(val: T.untyped).returns(T.nilable(T::Boolean)) }
+    def dry_struct?(val)
+      defined?(::Dry::Struct) && val.is_a?(Class) && val < ::Dry::Struct
+    end
+
+    # Generate a JSON Schema from a T::Struct class by introspecting its props.
+    sig { params(struct_class: T.class_of(T::Struct)).returns(T::Hash[String, T.untyped]) }
+    def t_struct_to_json_schema(struct_class) # rubocop:disable Metrics
+      properties = {}
+      required = []
+
+      T.unsafe(struct_class).props.each do |name, meta|
+        prop_name = (meta[:serialized_form] || name).to_s
+        properties[prop_name] = t_type_to_json_schema(meta[:type_object] || meta[:type])
+        required << prop_name unless meta[:fully_optional] || meta[:_tnilable]
+      end
+
+      schema = { 'type' => 'object', 'properties' => properties }
+      schema['required'] = required unless required.empty?
+      schema
+    end
+
+    # Convert a Sorbet T::Types type object to a JSON Schema hash.
+    sig { params(type: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def t_type_to_json_schema(type) # rubocop:disable Metrics
+      case type
+      when T::Types::Simple
+        PRIMITIVE_SCHEMAS[type.raw_type] || {}
+      when T::Types::Union
+        schemas = type.types.map { |t| t_type_to_json_schema(t) }
+        schemas.uniq!
+        schemas.length == 1 ? schemas.first : { 'anyOf' => schemas }
+      when T::Types::TypedArray
+        { 'type' => 'array', 'items' => t_type_to_json_schema(type.type) }
+      when T::Types::TypedHash
+        { 'type' => 'object' }
+      when Class
+        return t_struct_to_json_schema(type) if type < T::Struct
+
+        PRIMITIVE_SCHEMAS[type] || {}
+      else
+        {}
+      end
+    end
+
+    # Generate a JSON Schema from a Dry::Struct class.
+    sig { params(struct_class: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def dry_struct_to_json_schema(struct_class)
+      properties = {}
+      required = []
+
+      struct_class.schema.each do |key|
+        name = key.name.to_s
+        properties[name] = dry_type_to_json_schema(key.type)
+        required << name if key.required?
+      end
+
+      schema = { 'type' => 'object', 'properties' => properties }
+      schema['required'] = required unless required.empty?
+      schema
+    end
+
+    # Convert a dry-types type to a JSON Schema hash.
+    sig { params(type: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def dry_type_to_json_schema(type) # rubocop:disable Metrics
+      type_class = type.class.name || ''
+
+      # Constrained -> unwrap
+      return dry_type_to_json_schema(type.type) if type_class.include?('Constrained') && type.respond_to?(:type)
+
+      # Sum -> anyOf
+      if type.respond_to?(:left) && type.respond_to?(:right)
+        left = dry_type_to_json_schema(type.left)
+        right = dry_type_to_json_schema(type.right)
+        return left if left == right
+
+        return { 'anyOf' => [left, right] }
+      end
+
+      # Array with member type
+      return { 'type' => 'array', 'items' => dry_type_to_json_schema(type.member) } if type.respond_to?(:member)
+
+      # Nominal type with primitive
+      return nominal_to_json_schema(type) if type.respond_to?(:primitive)
+
+      {}
+    end
+
+    # Convert a nominal dry-type (with .primitive) to JSON Schema.
+    sig { params(type: T.untyped).returns(T::Hash[String, T.untyped]) }
+    def nominal_to_json_schema(type)
+      prim = type.primitive
+      return dry_struct_to_json_schema(prim) if dry_struct?(prim)
+
+      PRIMITIVE_SCHEMAS[prim] || {}
+    end
+  end
+
+  # Serde wrapper for primitive types and classes with a .json_schema method.
+  # Delegates serialize/deserialize to JsonSerde, adds schema.
+  class TypeSerde
+    extend T::Sig
+
+    # Create a TypeSerde for the given type with a precomputed JSON Schema.
+    sig { params(type: T.untyped, schema: T.nilable(T::Hash[String, T.untyped])).void }
+    def initialize(type, schema)
+      @type = type
+      @schema = schema
+    end
+
+    # Serialize a Ruby object to JSON bytes via JsonSerde.
+    sig { params(obj: T.untyped).returns(String) }
+    def serialize(obj)
+      JsonSerde.serialize(obj)
+    end
+
+    # Deserialize JSON bytes to a Ruby object via JsonSerde.
+    sig { params(buf: T.nilable(String)).returns(T.untyped) }
+    def deserialize(buf)
+      JsonSerde.deserialize(buf)
+    end
+
+    # Return the JSON Schema for this type.
+    sig { returns(T.nilable(T::Hash[String, T.untyped])) }
+    def json_schema
+      @schema
+    end
+  end
+
+  # Serde for Dry::Struct types.
+  # Deserializes JSON into struct instances, serializes structs to JSON.
+  class DryStructSerde
+    extend T::Sig
+
+    # Create a DryStructSerde for the given Dry::Struct class.
+    sig { params(struct_class: T.untyped).void }
+    def initialize(struct_class)
+      @struct_class = struct_class
+    end
+
+    # Serialize a Dry::Struct (or hash-like object) to JSON bytes.
+    sig { params(obj: T.untyped).returns(String) }
+    def serialize(obj)
+      return ''.b if obj.nil?
+
+      hash = obj.respond_to?(:to_h) ? obj.to_h : obj
+      JSON.generate(hash).b
+    end
+
+    # Deserialize JSON bytes into a Dry::Struct instance.
+    sig { params(buf: T.nilable(String)).returns(T.untyped) }
+    def deserialize(buf)
+      return nil if buf.nil? || buf.empty?
+
+      hash = JSON.parse(buf, symbolize_names: true)
+      @struct_class.new(**hash)
+    end
+
+    # Return the JSON Schema derived from the Dry::Struct definition.
+    sig { returns(T::Hash[String, T.untyped]) }
+    def json_schema
+      @json_schema ||= Serde.dry_struct_to_json_schema(@struct_class)
+    end
+  end
+
+  # Serde for T::Struct types (Sorbet's native typed structs).
+  # Uses T::Struct#serialize for output and T::Struct.from_hash for input.
+  # Generates JSON Schema from T::Struct props introspection.
+  class TStructSerde
+    extend T::Sig
+
+    # Create a TStructSerde for the given T::Struct subclass.
+    sig { params(struct_class: T.class_of(T::Struct)).void }
+    def initialize(struct_class)
+      @struct_class = struct_class
+    end
+
+    # Serialize a T::Struct instance to JSON bytes.
+    sig { params(obj: T.untyped).returns(String) }
+    def serialize(obj)
+      return ''.b if obj.nil?
+
+      hash = obj.is_a?(T::Struct) ? obj.serialize : obj
+      JSON.generate(hash).b
+    end
+
+    # Deserialize JSON bytes into a T::Struct instance.
+    sig { params(buf: T.nilable(String)).returns(T.untyped) }
+    def deserialize(buf)
+      return nil if buf.nil? || buf.empty?
+
+      hash = JSON.parse(buf)
+      T.unsafe(@struct_class).from_hash(hash)
+    end
+
+    # Return the JSON Schema derived from the T::Struct props.
+    sig { returns(T::Hash[String, T.untyped]) }
+    def json_schema
+      @json_schema ||= Serde.t_struct_to_json_schema(@struct_class)
+    end
+  end
+end

data/lib/restate/server.rb

@@ -0,0 +1,280 @@
+# typed: true
+# 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
+    extend T::Sig
+
+    SDK_VERSION = T.let(Internal::SDK_VERSION, String)
+    X_RESTATE_SERVER = T.let("restate-sdk-ruby/#{SDK_VERSION}".freeze, String)
+
+    LOGGER = T.let(Logger.new($stdout, progname: 'Restate::Server'), Logger)
+
+    sig { params(endpoint: Endpoint).void }
+    def initialize(endpoint)
+      @endpoint = T.let(endpoint, Endpoint)
+      @identity_verifier = T.let(Internal::IdentityVerifier.new(endpoint.identity_keys), Internal::IdentityVerifier)
+    end
+
+    # Rack interface
+    sig { params(env: T::Hash[String, T.untyped]).returns(T.untyped) }
+    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
+
+    sig { params(path: String).returns(T::Hash[Symbol, T.untyped]) }
+    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
+
+    sig { returns(T.untyped) }
+    def health_response
+      [200, { 'content-type' => 'application/json', 'x-restate-server' => X_RESTATE_SERVER }, ['{"status":"ok"}']]
+    end
+
+    sig { returns(T.untyped) }
+    def not_found_response
+      [404, { 'x-restate-server' => X_RESTATE_SERVER }, ['']]
+    end
+
+    sig { params(status: Integer, message: String).returns(T.untyped) }
+    def error_response(status, message)
+      [status, { 'content-type' => 'text/plain', 'x-restate-server' => X_RESTATE_SERVER }, [message]]
+    end
+
+    sig { params(env: T::Hash[String, T.untyped]).returns(T.untyped) }
+    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
+
+    sig { params(accept: String).returns(T.nilable(Integer)) }
+    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
+
+    sig { params(env: T::Hash[String, T.untyped], service_name: T.untyped, handler_name: T.untyped).returns(T.untyped) }
+    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
+
+    sig { params(env: T::Hash[String, T.untyped], handler: T.untyped, request_headers: T.untyped).returns(T.untyped) }
+    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 = T.let(false, T::Boolean)
+      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
+      )
+
+      # 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
+      extend T::Sig
+
+      sig { params(queue: Async::Queue).void }
+      def initialize(queue)
+        @queue = T.let(queue, Async::Queue)
+      end
+
+      def each
+        loop do
+          chunk = @queue.dequeue
+          break if chunk.nil?
+
+          yield chunk
+        end
+      end
+    end
+
+    sig { params(env: T::Hash[String, T.untyped]).returns(T::Array[T::Array[String]]) }
+    def extract_headers(env)
+      headers = T.let([], T::Array[T::Array[String]])
+      env.each do |key, value|
+        next unless key.start_with?('HTTP_')
+
+        header_name = key.sub('HTTP_', '').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