restate-sdk 0.4.3

data/lib/restate/vm.rb

@@ -0,0 +1,325 @@
+# typed: true
+# frozen_string_literal: true
+
+require_relative 'restate_internal'
+
+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)
+
+  class NotReady; end
+  class Suspended; end
+
+  NOT_READY = T.let(NotReady.new.freeze, NotReady)
+  SUSPENDED = T.let(Suspended.new.freeze, Suspended)
+  CANCEL_HANDLE = T.let(Internal::CANCEL_NOTIFICATION_HANDLE, Integer)
+
+  # Progress loop result types
+  class DoProgressAnyCompleted; end
+  class DoProgressReadFromInput; end
+  class DoProgressCancelSignalReceived; end
+  class DoWaitPendingRun; end
+
+  DO_PROGRESS_ANY_COMPLETED = T.let(DoProgressAnyCompleted.new.freeze, DoProgressAnyCompleted)
+  DO_PROGRESS_READ_FROM_INPUT = T.let(DoProgressReadFromInput.new.freeze, DoProgressReadFromInput)
+  DO_PROGRESS_CANCEL_SIGNAL_RECEIVED = T.let(DoProgressCancelSignalReceived.new.freeze, DoProgressCancelSignalReceived)
+  DO_WAIT_PENDING_RUN = T.let(DoWaitPendingRun.new.freeze, DoWaitPendingRun)
+
+  DoProgressExecuteRun = Struct.new(:handle, keyword_init: true)
+
+  # User-facing retry policy for ctx.run
+  RunRetryPolicy = Struct.new(
+    :initial_interval, :max_attempts, :max_duration,
+    :max_interval, :interval_factor,
+    keyword_init: true
+  )
+
+  # Exponential retry configuration for run
+  RunRetryConfig = Struct.new(
+    :initial_interval, :max_attempts, :max_duration,
+    :max_interval, :interval_factor,
+    keyword_init: true
+  )
+
+  # Wraps the native Restate::Internal::VM, mapping native types to Ruby types.
+  class VMWrapper
+    extend T::Sig
+
+    sig { params(headers: T.untyped).void }
+    def initialize(headers)
+      @vm = T.let(Internal::VM.new(headers), Internal::VM)
+    end
+
+    sig { returns([Integer, T.untyped]) }
+    def get_response_head
+      result = @vm.get_response_head
+      [result.status_code, result.headers]
+    end
+
+    sig { params(buf: String).void }
+    def notify_input(buf)
+      @vm.notify_input(buf)
+    end
+
+    sig { void }
+    def notify_input_closed
+      @vm.notify_input_closed
+    end
+
+    sig { params(error: String, stacktrace: T.nilable(String)).void }
+    def notify_error(error, stacktrace = nil)
+      @vm.notify_error(error, stacktrace)
+    end
+
+    sig { returns(T.nilable(String)) }
+    def take_output
+      @vm.take_output
+    end
+
+    sig { returns(T::Boolean) }
+    def is_ready_to_execute
+      @vm.is_ready_to_execute
+    end
+
+    sig { params(handle: Integer).returns(T::Boolean) }
+    def is_completed(handle)
+      @vm.is_completed(handle)
+    end
+
+    sig { params(handles: T::Array[Integer]).returns(T.untyped) }
+    def do_progress(handles)
+      result = @vm.do_progress(handles)
+      map_do_progress(result)
+    rescue Internal::VMError => e
+      e
+    end
+
+    sig { params(handle: Integer).returns(T.untyped) }
+    def take_notification(handle)
+      result = @vm.take_notification(handle)
+      map_notification(result)
+    rescue Internal::VMError => e
+      e
+    end
+
+    sig { returns(T.untyped) }
+    def sys_input
+      inp = @vm.sys_input
+      headers = inp.headers.map { |h| [h.key, h.value] }
+      Invocation.new(
+        invocation_id: inp.invocation_id,
+        random_seed: inp.random_seed,
+        headers: headers,
+        input_buffer: inp.input.b,
+        key: inp.key
+      )
+    end
+
+    sig { params(name: String).returns(Integer) }
+    def sys_get_state(name)
+      @vm.sys_get_state(name)
+    end
+
+    sig { returns(Integer) }
+    def sys_get_state_keys
+      @vm.sys_get_state_keys
+    end
+
+    sig { params(name: String, value: String).void }
+    def sys_set_state(name, value)
+      @vm.sys_set_state(name, value)
+    end
+
+    sig { params(name: String).void }
+    def sys_clear_state(name)
+      @vm.sys_clear_state(name)
+    end
+
+    sig { void }
+    def sys_clear_all_state
+      @vm.sys_clear_all_state
+    end
+
+    sig { params(millis: Integer, name: T.nilable(String)).returns(Integer) }
+    def sys_sleep(millis, name = nil)
+      # Rust side always expects 2 args: (millis, name_or_nil)
+      @vm.sys_sleep(millis, name)
+    end
+
+    sig do
+      params(
+        service: String,
+        handler: String,
+        parameter: String,
+        key: T.nilable(String),
+        idempotency_key: T.nilable(String),
+        headers: T.nilable(T::Hash[String, String])
+      ).returns(Internal::CallHandle)
+    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)
+      hdr_array = headers&.map { |k, v| [k, v] }
+      @vm.sys_call(service, handler, parameter, key, idempotency_key, hdr_array)
+    end
+
+    sig do
+      params(
+        service: String,
+        handler: String,
+        parameter: String,
+        key: T.nilable(String),
+        delay: T.nilable(Integer),
+        idempotency_key: T.nilable(String),
+        headers: T.nilable(T::Hash[String, String])
+      ).returns(Integer)
+    end
+    def sys_send(service:, handler:, parameter:, key: nil, delay: nil, idempotency_key: nil, headers: nil)
+      # Rust side expects 7 args
+      hdr_array = headers&.map { |k, v| [k, v] }
+      @vm.sys_send(service, handler, parameter, key, delay, idempotency_key, hdr_array)
+    end
+
+    sig { params(name: String).returns(Integer) }
+    def sys_run(name)
+      @vm.sys_run(name)
+    end
+
+    sig { params(handle: Integer, output: String).void }
+    def propose_run_completion_success(handle, output)
+      @vm.propose_run_completion_success(handle, output)
+    end
+
+    sig { params(handle: Integer, failure: T.untyped).void }
+    def propose_run_completion_failure(handle, failure)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      @vm.propose_run_completion_failure(handle, native_failure)
+    end
+
+    sig do
+      params(
+        handle: Integer,
+        failure: T.untyped,
+        attempt_duration_ms: Integer,
+        config: T.untyped
+      ).void
+    end
+    def propose_run_completion_transient(handle, failure:, attempt_duration_ms:, config:)
+      native_failure = Internal::Failure.new(failure.code, failure.message, failure.stacktrace)
+      native_config = Internal::ExponentialRetryConfig.new(
+        config.initial_interval, config.max_attempts,
+        config.max_duration, config.max_interval,
+        config.interval_factor
+      )
+      @vm.propose_run_completion_failure_transient(handle, native_failure, attempt_duration_ms, native_config)
+    end
+
+    sig { params(output: String).void }
+    def sys_write_output_success(output)
+      @vm.sys_write_output_success(output)
+    end
+
+    sig { params(failure: T.untyped).void }
+    def sys_write_output_failure(failure)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      @vm.sys_write_output_failure(native_failure)
+    end
+
+    sig { void }
+    def sys_end
+      @vm.sys_end
+    end
+
+    sig { returns(T::Boolean) }
+    def is_replaying
+      @vm.is_replaying
+    end
+
+    # Returns [awakeable_id (String), notification_handle (Integer)]
+    sig { returns([String, Integer]) }
+    def sys_awakeable
+      @vm.sys_awakeable
+    end
+
+    sig { params(awakeable_id: String, value: String).void }
+    def sys_complete_awakeable_success(awakeable_id, value)
+      @vm.sys_complete_awakeable_success(awakeable_id, value)
+    end
+
+    sig { params(awakeable_id: String, failure: T.untyped).void }
+    def sys_complete_awakeable_failure(awakeable_id, failure)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      @vm.sys_complete_awakeable_failure(awakeable_id, native_failure)
+    end
+
+    sig { params(key: String).returns(Integer) }
+    def sys_get_promise(key)
+      @vm.sys_get_promise(key)
+    end
+
+    sig { params(key: String).returns(Integer) }
+    def sys_peek_promise(key)
+      @vm.sys_peek_promise(key)
+    end
+
+    sig { params(key: String, value: String).returns(Integer) }
+    def sys_complete_promise_success(key, value)
+      @vm.sys_complete_promise_success(key, value)
+    end
+
+    sig { params(key: String, failure: T.untyped).returns(Integer) }
+    def sys_complete_promise_failure(key, failure)
+      native_failure = Internal::Failure.new(failure.code, failure.message, nil)
+      @vm.sys_complete_promise_failure(key, native_failure)
+    end
+
+    sig { params(invocation_id: String).void }
+    def sys_cancel_invocation(invocation_id)
+      @vm.sys_cancel_invocation(invocation_id)
+    end
+
+    private
+
+    sig { params(result: T.untyped).returns(T.untyped) }
+    def map_do_progress(result)
+      case result
+      when Internal::Suspended
+        SUSPENDED
+      when Internal::DoProgressAnyCompleted
+        DO_PROGRESS_ANY_COMPLETED
+      when Internal::DoProgressReadFromInput
+        DO_PROGRESS_READ_FROM_INPUT
+      when Internal::DoProgressExecuteRun
+        DoProgressExecuteRun.new(handle: result.handle)
+      when Internal::DoProgressCancelSignalReceived
+        DO_PROGRESS_CANCEL_SIGNAL_RECEIVED
+      when Internal::DoWaitForPendingRun
+        DO_WAIT_PENDING_RUN
+      else
+        raise "Unknown progress type: #{result.class}"
+      end
+    end
+
+    sig { params(result: T.untyped).returns(T.untyped) }
+    def map_notification(result)
+      case result
+      when Internal::Suspended
+        SUSPENDED
+      when NilClass
+        NOT_READY
+      when Internal::Void
+        nil
+      when String
+        # Could be bytes (success) or invocation_id string.
+        # The native layer returns RString for both.
+        result
+      when Internal::Failure
+        Failure.new(code: result.code, message: result.message)
+      when Internal::StateKeys
+        result.keys
+      else
+        raise "Unknown notification type: #{result.class}"
+      end
+    end
+  end
+end

data/lib/restate/workflow.rb

@@ -0,0 +1,57 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # A durable workflow with a main entry point and shared handlers.
+  #
+  # @example
+  #   class Signup < Restate::Workflow
+  #     main def run(email)
+  #       # workflow logic
+  #     end
+  #
+  #     handler def status
+  #       ctx = Restate.current_workflow_context
+  #       ctx.get("status")
+  #     end
+  #   end
+  class Workflow
+    extend T::Sig
+    extend ServiceDSL
+
+    # Register the main workflow entry point.
+    # Use as: +main def run(arg)+ or +main :run, input: String+
+    #
+    # @param method_name [Symbol] name of the method to register
+    # @param opts [Hash] handler options (+input:+, +output:+, +accept:+, +content_type:+)
+    # @return [Symbol] the method name
+    def self.main(method_name = nil, **opts)
+      if method_name.is_a?(String)
+        raise ArgumentError,
+              "handler expects a Symbol (use `main def #{method_name}(...)` or `main :#{method_name}`)"
+      end
+      return method_name unless method_name.is_a?(Symbol)
+
+      _register_handler(method_name, **T.unsafe({ kind: 'workflow', **opts }))
+    end
+
+    # Register a shared handler on this workflow.
+    #
+    # @param method_name [Symbol] name of the method to register
+    # @param opts [Hash] handler options (+input:+, +output:+, +accept:+, +content_type:+)
+    # @return [Symbol] the method name
+    def self.handler(method_name = nil, **opts)
+      if method_name.is_a?(String)
+        raise ArgumentError,
+              "handler expects a Symbol (use `handler def #{method_name}(...)` or `handler :#{method_name}`)"
+      end
+      return method_name unless method_name.is_a?(Symbol)
+
+      _register_handler(method_name, **T.unsafe({ kind: 'shared', **opts }))
+    end
+
+    def self._service_kind
+      'workflow'
+    end
+  end
+end

data/lib/restate.rb

@@ -0,0 +1,130 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
+require_relative 'restate/version'
+require_relative 'restate/errors'
+require_relative 'restate/serde'
+require_relative 'restate/vm'
+require_relative 'restate/context'
+require_relative 'restate/handler'
+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'
+
+# Restate Ruby SDK — build resilient applications with durable execution.
+module Restate
+  extend T::Sig
+
+  module_function
+
+  # Create an endpoint, optionally binding services.
+  # Returns an Endpoint that can be further configured before calling +.app+.
+  #
+  # @param services [Array<Class>] service classes or instances to bind
+  # @return [Endpoint]
+  sig do
+    params(
+      services: T.untyped,
+      protocol: T.nilable(String),
+      identity_keys: T.nilable(T::Array[String])
+    ).returns(Endpoint)
+  end
+  def endpoint(*services, protocol: nil, identity_keys: nil)
+    ep = Endpoint.new
+    ep.streaming_protocol if protocol == 'bidi'
+    ep.request_response_protocol if protocol == 'request_response'
+    services.each { |s| ep.bind(s) }
+    identity_keys&.each { |k| ep.identity_key(k) }
+    ep
+  end
+
+  # ── Fiber-local context accessors ──
+  #
+  # The SDK stores the current handler context in fiber-local storage
+  # (Thread.current[], which is fiber-scoped in Ruby). These methods
+  # retrieve it with the appropriate type for IDE completion.
+  #
+  # Use these instead of the +ctx+ parameter when you need the context
+  # from a nested method that doesn't have +ctx+ in scope.
+
+  # Returns the current context for a Service handler.
+  # Raises if called outside a Restate handler.
+  #
+  # @return [Context]
+  sig { returns(Context) }
+  def current_context
+    fetch_context!
+  end
+
+  # Returns the current context for a VirtualObject exclusive handler.
+  # Raises if not inside a VirtualObject exclusive handler.
+  #
+  # @return [ObjectContext]
+  sig { returns(ObjectContext) }
+  def current_object_context
+    fetch_context!(service_kind: 'object', handler_kind: 'exclusive')
+  end
+
+  # Returns the current context for a VirtualObject shared handler.
+  # Read-only state: +get+ and +state_keys+ only, no +set+/+clear+.
+  # Raises if not inside a VirtualObject shared handler.
+  #
+  # @return [ObjectSharedContext]
+  sig { returns(ObjectSharedContext) }
+  def current_shared_context
+    fetch_context!(service_kind: 'object', handler_kind: 'shared')
+  end
+
+  # Returns the current context for a Workflow main handler.
+  # Raises if not inside a Workflow main handler.
+  #
+  # @return [WorkflowContext]
+  sig { returns(WorkflowContext) }
+  def current_workflow_context
+    fetch_context!(service_kind: 'workflow', handler_kind: 'workflow')
+  end
+
+  # Returns the current context for a Workflow shared handler.
+  # Read-only state: +get+ and +state_keys+ only, no +set+/+clear+.
+  # Raises if not inside a Workflow shared handler.
+  #
+  # @return [WorkflowSharedContext]
+  sig { returns(WorkflowSharedContext) }
+  def current_shared_workflow_context
+    fetch_context!(service_kind: 'workflow', handler_kind: 'shared')
+  end
+
+  # @!visibility private
+  sig do
+    params(service_kind: T.nilable(String), handler_kind: T.nilable(String)).returns(ServerContext)
+  end
+  def fetch_context!(service_kind: nil, handler_kind: nil) # rubocop:disable Metrics
+    ctx = Thread.current[:restate_context]
+    unless ctx
+      Kernel.raise 'Not inside a Restate handler. ' \
+                   'Context accessors can only be called during handler execution.'
+    end
+
+    if service_kind
+      actual_service = Thread.current[:restate_service_kind]
+      unless actual_service == service_kind
+        Kernel.raise "Expected a #{service_kind} handler, but current handler is #{actual_service || 'unknown'}."
+      end
+    end
+
+    if handler_kind
+      actual_handler = Thread.current[:restate_handler_kind]
+      unless actual_handler == handler_kind
+        Kernel.raise "Expected a #{handler_kind} handler, but current handler kind is #{actual_handler || 'unknown'}."
+      end
+    end
+
+    T.cast(ctx, ServerContext)
+  end
+end

data/lib/tapioca/dsl/compilers/restate.rb

@@ -0,0 +1,45 @@
+# typed: false
+# frozen_string_literal: true
+
+return unless defined?(Tapioca::Dsl::Compiler)
+
+module Tapioca
+  module Dsl
+    module Compilers
+      # Generates Sorbet sigs for Restate handler methods.
+      #
+      # Handlers no longer receive +ctx+ as a parameter — context is accessed
+      # via fiber-local +Restate.current_context+ (or typed variants). This
+      # compiler generates sigs reflecting the actual handler arity (0 or 1).
+      #
+      # Usage:
+      #   bundle exec tapioca dsl
+      class Restate < Compiler
+        ConstantType = type_member { { fixed: Module } }
+
+        class << self
+          def gather_constants
+            all_classes.select do |klass|
+              klass.is_a?(Class) && (
+                klass < ::Restate::Service ||
+                klass < ::Restate::VirtualObject ||
+                klass < ::Restate::Workflow
+              )
+            rescue TypeError
+              false
+            end
+          end
+        end
+
+        def decorate
+          root.create_path(constant) do |klass|
+            constant.handlers.each do |name, handler|
+              params = handler.arity == 1 ? [create_param('input', type: 'T.untyped')] : []
+              klass.create_method(name, parameters: params, return_type: 'T.untyped')
+            end
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: restate-sdk
+version: !ruby/object:Gem::Version
+  version: 0.4.3
+platform: ruby
+authors:
+- Restate Developers
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: falcon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.47'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.47'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Build resilient applications with distributed durable async/await using
+  Restate
+email:
+- code@restate.dev
+executables: []
+extensions:
+- ext/restate_internal/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- README.md
+- ext/restate_internal/Cargo.toml
+- ext/restate_internal/extconf.rb
+- ext/restate_internal/src/lib.rs
+- lib/restate.rb
+- lib/restate/context.rb
+- lib/restate/discovery.rb
+- lib/restate/durable_future.rb
+- lib/restate/endpoint.rb
+- lib/restate/errors.rb
+- lib/restate/handler.rb
+- lib/restate/serde.rb
+- lib/restate/server.rb
+- lib/restate/server_context.rb
+- lib/restate/service.rb
+- lib/restate/service_dsl.rb
+- lib/restate/testing.rb
+- lib/restate/version.rb
+- lib/restate/virtual_object.rb
+- lib/restate/vm.rb
+- lib/restate/workflow.rb
+- lib/tapioca/dsl/compilers/restate.rb
+homepage: https://github.com/restatedev/sdk-ruby
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Restate SDK for Ruby
+test_files: []