restate-sdk 0.6.0 → 0.8.0

data/lib/restate.rb

@@ -1,7 +1,6 @@
 # typed: true
 # frozen_string_literal: true
 
-require 'sorbet-runtime'
 require_relative 'restate/version'
 require_relative 'restate/errors'
 require_relative 'restate/serde'
@@ -16,11 +15,21 @@ require_relative 'restate/server_context'
 require_relative 'restate/durable_future'
 require_relative 'restate/discovery'
 require_relative 'restate/endpoint'
+require_relative 'restate/service_proxy'
+require_relative 'restate/config'
+require_relative 'restate/client'
 
 # Restate Ruby SDK — build resilient applications with durable execution.
-module Restate
-  extend T::Sig
-
+#
+# All handler-facing operations are available as module methods on +Restate+.
+# Inside a handler, call +Restate.run_sync+, +Restate.sleep+, +Restate.get+,
+# etc. directly — no context parameter needed.
+#
+# The context is stored in +Thread.current[]+ (fiber-scoped in Ruby 3.0+).
+# We intentionally use +Thread.current[]+ rather than +Fiber[]+ (Ruby 3.2+)
+# because +Thread.current[]+ is NOT inherited by child fibers, which prevents
+# accidental context leaks when Async spawns child tasks for run blocks.
+module Restate # rubocop:disable Metrics/ModuleLength
   module_function
 
   # Create an endpoint, optionally binding services.
@@ -28,13 +37,6 @@ module Restate
   #
   # @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'
@@ -44,71 +46,46 @@ module Restate
     ep
   end
 
-  # ── Fiber-local context accessors ──
-  #
-  # The SDK passes the context as the first argument to every handler.
-  # It is also stored 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 from nested helper methods that don'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
+  # ── Global configuration ──
 
-  # Returns the current context for a VirtualObject exclusive handler.
-  # Raises if not inside a VirtualObject exclusive handler.
+  # Configure the SDK globally. Settings are used by +Restate.client+.
   #
-  # @return [ObjectContext]
-  sig { returns(ObjectContext) }
-  def current_object_context
-    fetch_context!(service_kind: 'object', handler_kind: 'exclusive')
+  # @example
+  #   Restate.configure do |c|
+  #     c.ingress_url = "http://localhost:8080"
+  #     c.admin_url   = "http://localhost:9070"
+  #   end
+  def configure(&)
+    yield config
   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')
+  # Returns the global configuration. Creates a default one on first access.
+  def config
+    @config = nil unless defined?(@config)
+    @config ||= Config.new
   end
 
-  # Returns the current context for a Workflow main handler.
-  # Raises if not inside a Workflow main handler.
+  # Returns a pre-configured Client using the global +config+.
+  # Creates a new Client on each call (stateless — safe to discard).
   #
-  # @return [WorkflowContext]
-  sig { returns(WorkflowContext) }
-  def current_workflow_context
-    fetch_context!(service_kind: 'workflow', handler_kind: 'workflow')
+  # @example
+  #   Restate.client.service(Greeter).greet("World")
+  #   Restate.client.resolve_awakeable(id, payload)
+  #   Restate.client.create_deployment("http://localhost:9080")
+  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)
   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
+  # ── Context accessor (internal) ──
 
   # @!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.'
+                   'Restate.* methods can only be called during handler execution.'
     end
 
     if service_kind
@@ -125,6 +102,189 @@ module Restate
       end
     end
 
-    T.cast(ctx, ServerContext)
+    ctx
+  end
+
+  # ── Durable execution ──
+
+  # Execute a durable side effect. The block runs at most once; the result
+  # is journaled and replayed on retries. Returns a DurableFuture.
+  def run(name, serde: JsonSerde, retry_policy: nil, background: false, &action)
+    fetch_context!.run(name, serde: serde, retry_policy: retry_policy, background: background, &action)
+  end
+
+  # Convenience shortcut for +run(...).await+. Returns the result directly.
+  def run_sync(name, serde: JsonSerde, retry_policy: nil, background: false, &action)
+    fetch_context!.run_sync(name, serde: serde, retry_policy: retry_policy, background: background, &action)
+  end
+
+  # Durable timer that survives handler restarts.
+  def sleep(seconds)
+    fetch_context!.sleep(seconds)
+  end
+
+  # ── State operations (VirtualObject / Workflow) ──
+
+  # Durably retrieve a state entry. Returns nil if unset.
+  def get(name, serde: JsonSerde)
+    fetch_context!.get(name, serde: serde)
+  end
+
+  # Durably retrieve a state entry, returning a DurableFuture instead of blocking.
+  def get_async(name, serde: JsonSerde)
+    fetch_context!.get_async(name, serde: serde)
+  end
+
+  # Durably set a state entry.
+  def set(name, value, serde: JsonSerde)
+    fetch_context!.set(name, value, serde: serde)
+  end
+
+  # Durably remove a single state entry.
+  def clear(name)
+    fetch_context!.clear(name)
+  end
+
+  # Durably remove all state entries.
+  def clear_all
+    fetch_context!.clear_all
+  end
+
+  # List all state entry names.
+  def state_keys
+    fetch_context!.state_keys
+  end
+
+  # List all state entry names, returning a DurableFuture.
+  def state_keys_async
+    fetch_context!.state_keys_async
+  end
+
+  # ── Service communication ──
+
+  # Durably call a handler on a Restate service.
+  def service_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil,
+                   input_serde: NOT_SET, output_serde: NOT_SET)
+    ctx = fetch_context!
+    ctx.service_call(service, handler, arg, key: key, idempotency_key: idempotency_key,
+                                            headers: headers, input_serde: input_serde, output_serde: output_serde)
+  end
+
+  # Fire-and-forget send to a Restate service handler.
+  def service_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil,
+                   headers: nil, input_serde: NOT_SET)
+    ctx = fetch_context!
+    ctx.service_send(service, handler, arg, key: key, delay: delay, idempotency_key: idempotency_key,
+                                            headers: headers, input_serde: input_serde)
+  end
+
+  # Durably call a handler on a Restate virtual object.
+  def object_call(service, handler, key, arg, idempotency_key: nil, headers: nil,
+                  input_serde: NOT_SET, output_serde: NOT_SET)
+    ctx = fetch_context!
+    ctx.object_call(service, handler, key, arg, idempotency_key: idempotency_key,
+                                                headers: headers, input_serde: input_serde, output_serde: output_serde)
+  end
+
+  # Fire-and-forget send to a Restate virtual object handler.
+  def object_send(service, handler, key, arg, delay: nil, idempotency_key: nil,
+                  headers: nil, input_serde: NOT_SET)
+    ctx = fetch_context!
+    ctx.object_send(service, handler, key, arg, delay: delay, idempotency_key: idempotency_key,
+                                                headers: headers, input_serde: input_serde)
+  end
+
+  # Durably call a handler on a Restate workflow.
+  def workflow_call(service, handler, key, arg, idempotency_key: nil, headers: nil,
+                    input_serde: NOT_SET, output_serde: NOT_SET)
+    ctx = fetch_context!
+    ctx.workflow_call(service, handler, key, arg,
+                      idempotency_key: idempotency_key, headers: headers,
+                      input_serde: input_serde, output_serde: output_serde)
+  end
+
+  # Fire-and-forget send to a Restate workflow handler.
+  def workflow_send(service, handler, key, arg, delay: nil, idempotency_key: nil,
+                    headers: nil, input_serde: NOT_SET)
+    ctx = fetch_context!
+    ctx.workflow_send(service, handler, key, arg, delay: delay, idempotency_key: idempotency_key,
+                                                  headers: headers, input_serde: input_serde)
+  end
+
+  # Durably call a handler using raw bytes (no serialization).
+  def generic_call(service, handler, arg, key: nil, idempotency_key: nil, headers: nil)
+    fetch_context!.generic_call(service, handler, arg, key: key,
+                                                       idempotency_key: idempotency_key, headers: headers)
+  end
+
+  # Fire-and-forget send using raw bytes (no serialization).
+  def generic_send(service, handler, arg, key: nil, delay: nil, idempotency_key: nil, headers: nil)
+    fetch_context!.generic_send(service, handler, arg, key: key, delay: delay,
+                                                       idempotency_key: idempotency_key, headers: headers)
+  end
+
+  # ── Awakeables ──
+
+  # Create an awakeable for external callbacks. Returns [awakeable_id, DurableFuture].
+  def awakeable(serde: JsonSerde)
+    fetch_context!.awakeable(serde: serde)
+  end
+
+  # Resolve an awakeable with a success value.
+  def resolve_awakeable(awakeable_id, payload, serde: JsonSerde)
+    fetch_context!.resolve_awakeable(awakeable_id, payload, serde: serde)
+  end
+
+  # Reject an awakeable with a terminal failure.
+  def reject_awakeable(awakeable_id, message, code: 500)
+    fetch_context!.reject_awakeable(awakeable_id, message, code: code)
+  end
+
+  # ── Promises (Workflow only) ──
+
+  # Get a durable promise value, blocking until resolved.
+  def promise(name, serde: JsonSerde)
+    fetch_context!.promise(name, serde: serde)
+  end
+
+  # Peek at a durable promise without blocking. Returns nil if not yet resolved.
+  def peek_promise(name, serde: JsonSerde)
+    fetch_context!.peek_promise(name, serde: serde)
+  end
+
+  # Resolve a durable promise with a value.
+  def resolve_promise(name, payload, serde: JsonSerde)
+    fetch_context!.resolve_promise(name, payload, serde: serde)
+  end
+
+  # Reject a durable promise with a terminal failure.
+  def reject_promise(name, message, code: 500)
+    fetch_context!.reject_promise(name, message, code: code)
+  end
+
+  # ── Futures ──
+
+  # Wait until any of the given futures completes. Returns [completed, remaining].
+  def wait_any(*futures)
+    fetch_context!.wait_any(*futures)
+  end
+
+  # ── Request metadata ──
+
+  # Returns metadata about the current invocation (id, headers, raw body).
+  def request
+    fetch_context!.request
+  end
+
+  # Returns the key for this virtual object or workflow invocation.
+  def key
+    fetch_context!.key
+  end
+
+  # ── Invocation control ──
+
+  # Request cancellation of another invocation.
+  def cancel_invocation(invocation_id)
+    fetch_context!.cancel_invocation(invocation_id)
   end
 end

data/sig/restate.rbs

@@ -0,0 +1,196 @@
+# Public API type signatures for the Restate Ruby SDK.
+# Used by Steep for static type checking and by Ruby LSP for IDE completion.
+
+module Restate
+  # ── Endpoint ──
+
+  def self.endpoint: (*untyped services, ?protocol: String?, ?identity_keys: Array[String]?) -> Endpoint
+  def self.configure: () { (Config) -> void } -> void
+  def self.config: () -> Config
+  def self.client: () -> Client
+
+  # ── Durable execution ──
+
+  def self.run: (String name, ?serde: untyped, ?retry_policy: untyped, ?background: bool) { () -> untyped } -> DurableFuture
+  def self.run_sync: (String name, ?serde: untyped, ?retry_policy: untyped, ?background: bool) { () -> untyped } -> untyped
+  def self.sleep: (Numeric seconds) -> DurableFuture
+
+  # ── State operations ──
+
+  def self.get: (String name, ?serde: untyped) -> untyped
+  def self.get_async: (String name, ?serde: untyped) -> DurableFuture
+  def self.set: (String name, untyped value, ?serde: untyped) -> void
+  def self.clear: (String name) -> void
+  def self.clear_all: () -> void
+  def self.state_keys: () -> Array[String]
+  def self.state_keys_async: () -> DurableFuture
+
+  # ── Service communication ──
+
+  def self.service_call: (untyped service, (String | Symbol) handler, untyped arg, ?key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
+  def self.service_send: (untyped service, (String | Symbol) handler, untyped arg, ?key: String?, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
+  def self.object_call: (untyped service, (String | Symbol) handler, String key, untyped arg, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
+  def self.object_send: (untyped service, (String | Symbol) handler, String key, untyped arg, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
+  def self.workflow_call: (untyped service, (String | Symbol) handler, String key, untyped arg, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped, ?output_serde: untyped) -> DurableCallFuture
+  def self.workflow_send: (untyped service, (String | Symbol) handler, String key, untyped arg, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?, ?input_serde: untyped) -> SendHandle
+  def self.generic_call: (String service, String handler, String arg, ?key: String?, ?idempotency_key: String?, ?headers: Hash[String, String]?) -> DurableCallFuture
+  def self.generic_send: (String service, String handler, String arg, ?key: String?, ?delay: Numeric?, ?idempotency_key: String?, ?headers: Hash[String, String]?) -> SendHandle
+
+  # ── Awakeables ──
+
+  def self.awakeable: (?serde: untyped) -> [String, DurableFuture]
+  def self.resolve_awakeable: (String awakeable_id, untyped payload, ?serde: untyped) -> void
+  def self.reject_awakeable: (String awakeable_id, String message, ?code: Integer) -> void
+
+  # ── Promises ──
+
+  def self.promise: (String name, ?serde: untyped) -> untyped
+  def self.peek_promise: (String name, ?serde: untyped) -> untyped
+  def self.resolve_promise: (String name, untyped payload, ?serde: untyped) -> void
+  def self.reject_promise: (String name, String message, ?code: Integer) -> void
+
+  # ── Futures / Metadata / Control ──
+
+  def self.wait_any: (*DurableFuture futures) -> [Array[DurableFuture], Array[DurableFuture]]
+  def self.request: () -> untyped
+  def self.key: () -> String
+  def self.cancel_invocation: (String invocation_id) -> void
+  def self.fetch_context!: (?service_kind: String?, ?handler_kind: String?) -> untyped
+
+  # ── Errors ──
+
+  class TerminalError < StandardError
+    attr_reader status_code: Integer
+    def initialize: (?String message, ?status_code: Integer) -> void
+  end
+
+  class SuspendedError < StandardError
+    def initialize: () -> void
+  end
+
+  class InternalError < StandardError
+    def initialize: () -> void
+  end
+
+  class DisconnectedError < StandardError
+    def initialize: () -> void
+  end
+
+  # ── Futures ──
+
+  class DurableFuture
+    attr_reader handle: Integer
+    def initialize: (untyped ctx, Integer handle, ?serde: untyped) -> void
+    def await: () -> untyped
+    def completed?: () -> bool
+  end
+
+  class DurableCallFuture < DurableFuture
+    def initialize: (untyped ctx, Integer result_handle, Integer invocation_id_handle, output_serde: untyped) -> void
+    def invocation_id: () -> String
+    def cancel: () -> void
+  end
+
+  class SendHandle
+    def initialize: (untyped ctx, Integer invocation_id_handle) -> void
+    def invocation_id: () -> String
+    def cancel: () -> void
+  end
+
+  # ── Config ──
+
+  class Config
+    attr_accessor ingress_url: String
+    attr_accessor admin_url: String
+    attr_accessor ingress_headers: Hash[String, String]
+    attr_accessor admin_headers: Hash[String, String]
+    def initialize: () -> void
+  end
+
+  # ── Client ──
+
+  class Client
+    def initialize: (?ingress_url: String, ?admin_url: String, ?ingress_headers: Hash[String, String], ?admin_headers: Hash[String, String]) -> void
+    def service: (untyped service) -> ClientServiceProxy
+    def object: (untyped service, String key) -> ClientServiceProxy
+    def workflow: (untyped service, String key) -> ClientServiceProxy
+    def resolve_awakeable: (String awakeable_id, untyped payload) -> void
+    def reject_awakeable: (String awakeable_id, String message, ?code: Integer) -> void
+    def cancel_invocation: (String invocation_id) -> void
+    def kill_invocation: (String invocation_id) -> void
+
+    private
+
+    def resolve_name: (untyped service) -> String
+    def post_ingress: (String path, untyped body) -> untyped
+    def post_admin: (String path, untyped body) -> untyped
+    def parse_response: (Net::HTTPResponse response) -> untyped
+  end
+
+  class ClientServiceProxy
+    def initialize: (String base_url, String service_name, String? key, Hash[String, String] headers) -> void
+  end
+
+  # ── Endpoint ──
+
+  class Endpoint
+    attr_reader services: Hash[String, untyped]
+    attr_reader identity_keys: Array[String]
+    attr_accessor protocol: String?
+    attr_reader middleware: Array[untyped]
+    def initialize: () -> void
+    def bind: (*untyped svcs) -> self
+    def streaming_protocol: () -> self
+    def request_response_protocol: () -> self
+    def identity_key: (String key) -> self
+    def use: (untyped klass, *untyped args, **untyped kwargs) -> self
+    def app: () -> untyped
+  end
+
+  # ── Service proxies ──
+
+  class ServiceCallProxy
+    def initialize: (untyped service_class, ?key: String?, ?call_method: Symbol) -> void
+  end
+
+  class ServiceSendProxy
+    def initialize: (untyped service_class, ?key: String?, ?send_method: Symbol, ?delay: Numeric?) -> void
+  end
+
+  # ── Service classes (declared but not checked — heavy metaprogramming) ──
+
+  class Service
+  end
+
+  class VirtualObject
+  end
+
+  class Workflow
+  end
+
+  # ── Internal ──
+
+  class Server
+    def initialize: (untyped endpoint) -> void
+  end
+
+  module JsonSerde
+    def self.serialize: (untyped obj) -> String
+    def self.deserialize: (String? buf) -> untyped
+    def self.json_schema: () -> Hash[String, untyped]?
+  end
+
+  module BytesSerde
+    def self.serialize: (untyped obj) -> String
+    def self.deserialize: (String? buf) -> String?
+    def self.json_schema: () -> Hash[String, untyped]?
+  end
+
+  class AttemptFinishedEvent
+    def set?: () -> bool
+    def wait: () -> void
+  end
+
+  NOT_SET: untyped
+  RunRetryPolicy: untyped
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restate-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Restate Developers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -38,20 +38,6 @@ dependencies:
     - - ">="
       - !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:
@@ -69,6 +55,8 @@ files:
 - ext/restate_internal/extconf.rb
 - ext/restate_internal/src/lib.rs
 - lib/restate.rb
+- lib/restate/client.rb
+- lib/restate/config.rb
 - lib/restate/context.rb
 - lib/restate/discovery.rb
 - lib/restate/durable_future.rb
@@ -80,13 +68,13 @@ files:
 - lib/restate/server_context.rb
 - lib/restate/service.rb
 - lib/restate/service_dsl.rb
+- lib/restate/service_proxy.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
-- rbi/restate-sdk.rbi
+- sig/restate.rbs
 homepage: https://github.com/restatedev/sdk-ruby
 licenses:
 - MIT