restate-sdk 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc7f07e2b3bd62dbf82cb815a5b66443586e339bb3ae896e6b94594fdce9fab4
-  data.tar.gz: 9066dc59318b6e14f249c249c59b03b8e075df6986cf2b2d8a3d9b93ca56614b
+  metadata.gz: 6c57bd9821f10bb65901d7da4ad7f6a38f9e64f81f36bd6eece1f2a9efcb7d57
+  data.tar.gz: c924c4d0f17f82012edaafba7d9867b2f78f2aecdd6fecc0a8f17cbd84c5f89a
 SHA512:
-  metadata.gz: 79b2cee29852e255f9745665f44b8d4450badc22319c59120a2988c9ccd9dfa88723529ffb5059dbf4c94d929722368e00a5a1887c0e32b48663196513768860
-  data.tar.gz: 8faf5c53ca4b7bc538ff348a3ccb99a0cdbac8a418d9263073f67a8476353d8c01fb714784c93237f644b35ea7f1ff08e89074a1e07a2761f9c0d59f892643d5
+  metadata.gz: 0153b6c412588938d243b1d806af7a4e38d9467a21296fd299b9a6c1da77296a208009a82ce264f7d2e6e722a03fcd7b33fa1e77525c736dde7f0286512ece83
+  data.tar.gz: 4218cc6a283aa5ddf29eaed2ffd9935769a098e58fa98d476687509da45c9ddf4e4bfc871b873cfe234c1239b44f4d4ad6810975e89b61e90017463b0a0bf3d7

data/Cargo.lock

@@ -569,7 +569,7 @@ dependencies = [
 
 [[package]]
 name = "restate_internal"
-version = "0.6.0"
+version = "0.7.0"
 dependencies = [
  "magnus",
  "rb-sys",

data/README.md

@@ -13,8 +13,20 @@
 require 'restate'
 
 class Greeter < Restate::Service
-  handler def greet(ctx, name)
-    ctx.run_sync('build-greeting') { "Hello, #{name}!" }
+  handler def greet(name)
+    Restate.run_sync('build-greeting') { "Hello, #{name}!" }
+  end
+end
+
+class Counter < Restate::VirtualObject
+  state :count, default: 0
+
+  handler def add(addend)
+    self.count += addend
+  end
+
+  shared def get
+    count
   end
 end
 ```
@@ -67,8 +79,8 @@ end
 
 class EventService < Restate::Service
   handler :register, input: RegistrationRequest, output: RegistrationResponse
-  def register(ctx, request)
-    registration_id = ctx.run_sync('create-registration') do
+  def register(request)
+    registration_id = Restate.run_sync('create-registration') do
       "reg_#{request.event_name}_#{rand(10_000)}"
     end
 

data/ext/restate_internal/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "restate_internal"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2021"
 publish = false
 

data/lib/restate/client.rb

@@ -0,0 +1,181 @@
+# typed: true
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+
+module Restate
+  # HTTP client for invoking Restate services and managing the Restate runtime
+  # from outside the Restate runtime.
+  #
+  # @example Via global config (recommended)
+  #   Restate.configure do |c|
+  #     c.ingress_url = "http://localhost:8080"
+  #     c.admin_url = "http://localhost:9070"
+  #   end
+  #   client = Restate.client
+  #   result = client.service(Greeter).greet("World")
+  #
+  # @example Standalone
+  #   client = Restate::Client.new(ingress_url: "http://localhost:8080",
+  #                                admin_url: "http://localhost:9070")
+  #
+  # @example Service invocation
+  #   client.service("Greeter").greet("World")
+  #   client.object("Counter", "my-key").add(5)
+  #   client.workflow("UserSignup", "user42").run("user@example.com")
+  #
+  # @example Admin operations
+  #   client.resolve_awakeable(awakeable_id, "result")
+  #   client.reject_awakeable(awakeable_id, "failed")
+  #   client.cancel_invocation(invocation_id)
+  #   client.create_deployment("http://localhost:9080")
+  class Client
+    extend T::Sig
+
+    sig do
+      params(ingress_url: String, admin_url: String,
+             ingress_headers: T::Hash[String, String],
+             admin_headers: T::Hash[String, String]).void
+    end
+    def initialize(ingress_url: 'http://localhost:8080', admin_url: 'http://localhost:9070',
+                   ingress_headers: {}, admin_headers: {})
+      @ingress_url = ingress_url.chomp('/')
+      @admin_url = admin_url.chomp('/')
+      @ingress_headers = ingress_headers
+      @admin_headers = admin_headers
+    end
+
+    # ── Service invocation proxies ──
+
+    # Returns a proxy for calling a stateless service.
+    sig { params(service: T.any(String, T::Class[T.anything])).returns(ClientServiceProxy) }
+    def service(service)
+      ClientServiceProxy.new(@ingress_url, resolve_name(service), nil, @ingress_headers)
+    end
+
+    # Returns a proxy for calling a keyed virtual object.
+    sig { params(service: T.any(String, T::Class[T.anything]), key: String).returns(ClientServiceProxy) }
+    def object(service, key)
+      ClientServiceProxy.new(@ingress_url, resolve_name(service), key, @ingress_headers)
+    end
+
+    # Returns a proxy for calling a workflow.
+    sig { params(service: T.any(String, T::Class[T.anything]), key: String).returns(ClientServiceProxy) }
+    def workflow(service, key)
+      ClientServiceProxy.new(@ingress_url, resolve_name(service), key, @ingress_headers)
+    end
+
+    # ── Awakeable operations ──
+
+    # Resolve an awakeable from outside the Restate runtime.
+    sig { params(awakeable_id: String, payload: T.untyped).void }
+    def resolve_awakeable(awakeable_id, payload)
+      post_ingress("/restate/awakeables/#{awakeable_id}/resolve", payload)
+    end
+
+    # Reject an awakeable from outside the Restate runtime.
+    sig { params(awakeable_id: String, message: String, code: Integer).void }
+    def reject_awakeable(awakeable_id, message, code: 500)
+      post_ingress("/restate/awakeables/#{awakeable_id}/reject",
+                   { 'message' => message, 'code' => code })
+    end
+
+    # ── Invocation management ──
+
+    # Cancel a running invocation.
+    sig { params(invocation_id: String).void }
+    def cancel_invocation(invocation_id)
+      post_admin("/restate/invocations/#{invocation_id}/cancel", nil)
+    end
+
+    # Kill a running invocation (immediate termination, no cleanup).
+    sig { params(invocation_id: String).void }
+    def kill_invocation(invocation_id)
+      post_admin("/restate/invocations/#{invocation_id}/kill", nil)
+    end
+
+    private
+
+    sig { params(service: T.any(String, T::Class[T.anything])).returns(String) }
+    def resolve_name(service)
+      if service.is_a?(Class) && service.respond_to?(:service_name)
+        T.unsafe(service).service_name
+      else
+        service.to_s
+      end
+    end
+
+    sig { params(path: String, body: T.untyped).returns(T.untyped) }
+    def post_ingress(path, body) # rubocop:disable Metrics/AbcSize
+      uri = URI("#{@ingress_url}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      @ingress_headers.each { |k, v| request[k] = v }
+      request.body = JSON.generate(body) if body
+      response = Net::HTTP.start(uri.hostname, uri.port,
+                                 use_ssl: uri.scheme == 'https',
+                                 read_timeout: 30) { |http| http.request(request) }
+      Kernel.raise "Restate ingress error: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+      parse_response(response)
+    end
+
+    sig { params(path: String, body: T.untyped).returns(T.untyped) }
+    def post_admin(path, body) # rubocop:disable Metrics/AbcSize
+      uri = URI("#{@admin_url}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      @admin_headers.each { |k, v| request[k] = v }
+      request.body = JSON.generate(body) if body
+      response = Net::HTTP.start(uri.hostname, uri.port,
+                                 use_ssl: uri.scheme == 'https',
+                                 read_timeout: 30) { |http| http.request(request) }
+      Kernel.raise "Restate admin error: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+      parse_response(response)
+    end
+
+    sig { params(response: Net::HTTPResponse).returns(T.untyped) }
+    def parse_response(response)
+      body = response.body
+      body && !body.empty? ? JSON.parse(body) : nil
+    end
+  end
+
+  # Proxy that sends HTTP requests to the Restate ingress for a specific service.
+  # Handler calls are forwarded via +method_missing+.
+  #
+  # @!visibility private
+  class ClientServiceProxy
+    extend T::Sig
+
+    sig do
+      params(base_url: String, service_name: String, key: T.nilable(String),
+             headers: T::Hash[String, String]).void
+    end
+    def initialize(base_url, service_name, key, headers)
+      @base_url = base_url
+      @service_name = service_name
+      @key = key
+      @headers = headers
+    end
+
+    def method_missing(handler_name, arg = nil) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      path = @key ? "/#{@service_name}/#{@key}/#{handler_name}" : "/#{@service_name}/#{handler_name}"
+      uri = URI("#{@base_url}#{path}")
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      @headers.each { |k, v| request[k] = v }
+      request.body = JSON.generate(arg)
+      response = Net::HTTP.start(uri.hostname, uri.port,
+                                 use_ssl: uri.scheme == 'https',
+                                 read_timeout: 30) { |http| http.request(request) }
+      Kernel.raise "Restate ingress error: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+      body = response.body
+      body && !body.empty? ? JSON.parse(body) : nil
+    end
+
+    def respond_to_missing?(_method_name, _include_private = false)
+      true
+    end
+  end
+end

data/lib/restate/config.rb

@@ -0,0 +1,42 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # Global SDK configuration. Set via +Restate.configure+.
+  #
+  # @example
+  #   Restate.configure do |c|
+  #     c.ingress_url = "http://localhost:8080"
+  #     c.admin_url   = "http://localhost:9070"
+  #   end
+  #
+  #   # Then use the pre-configured client:
+  #   Restate.client.service(Greeter).greet("World")
+  class Config
+    extend T::Sig
+
+    # Restate ingress URL (for invoking services).
+    sig { returns(String) }
+    attr_accessor :ingress_url
+
+    # Restate admin URL (for deployments, invocation management).
+    sig { returns(String) }
+    attr_accessor :admin_url
+
+    # Default headers sent with every ingress request.
+    sig { returns(T::Hash[String, String]) }
+    attr_accessor :ingress_headers
+
+    # Default headers sent with every admin request.
+    sig { returns(T::Hash[String, String]) }
+    attr_accessor :admin_headers
+
+    sig { void }
+    def initialize
+      @ingress_url = T.let('http://localhost:8080', String)
+      @admin_url = T.let('http://localhost:9070', String)
+      @ingress_headers = T.let({}, T::Hash[String, String])
+      @admin_headers = T.let({}, T::Hash[String, String])
+    end
+  end
+end

data/lib/restate/handler.rb

@@ -41,19 +41,20 @@ module Restate
   end
   def invoke_handler(handler:, ctx:, in_buffer:, middleware: []) # rubocop:disable Metrics/AbcSize
     call_handler = Kernel.proc do
-      if handler.arity == 2
+      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
-        handler.callable.call(ctx, in_arg)
+        handler.callable.call(in_arg)
       else
-        handler.callable.call(ctx)
+        handler.callable.call
       end
     end
 
     # Build the middleware chain so each middleware can use `yield` to call the next.
+    # Middleware still receives (handler, ctx) for low-level access.
     chain = middleware.reverse.reduce(call_handler) do |nxt, mw|
       Kernel.proc { mw.call(handler, ctx, &nxt) }
     end

data/lib/restate/service.rb

@@ -30,6 +30,28 @@ module Restate
       _register_handler(method_name, **T.unsafe({ kind: nil, **opts }))
     end
 
+    # Returns a call proxy for fluent durable calls to this service.
+    #
+    # @example
+    #   Greeter.call.greet("World").await
+    #
+    # @return [ServiceCallProxy]
+    def self.call
+      ServiceCallProxy.new(self, call_method: :service_call)
+    end
+
+    # Returns a send proxy for fluent fire-and-forget sends to this service.
+    #
+    # @example
+    #   Greeter.send!.greet("World")
+    #   Greeter.send!(delay: 60).greet("World")
+    #
+    # @param delay [Numeric, nil] optional delay in seconds
+    # @return [ServiceSendProxy]
+    def self.send!(delay: nil)
+      ServiceSendProxy.new(self, send_method: :service_send, delay: delay)
+    end
+
     def self._service_kind
       'service'
     end

data/lib/restate/service_dsl.rb

@@ -31,6 +31,70 @@ module Restate
       subclass.instance_variable_set(:@_idempotency_retention, nil)
       subclass.instance_variable_set(:@_ingress_private, nil)
       subclass.instance_variable_set(:@_invocation_retry_policy, nil)
+      subclass.instance_variable_set(:@_state_declarations, {})
+    end
+
+    # Declare a durable state entry with auto-generated getter, setter, and clear methods.
+    # Only available on VirtualObject and Workflow.
+    #
+    # The generated methods delegate to the current Restate context via +Thread.current+
+    # (fiber-scoped in Ruby 3.0+), so they work correctly across concurrent invocations.
+    #
+    # @param name [Symbol] state key name
+    # @param default [Object, nil] default value returned when state is not set
+    # @param serde [Object] serializer/deserializer (defaults to JsonSerde)
+    #
+    # @example
+    #   class Counter < Restate::VirtualObject
+    #     state :count, default: 0
+    #
+    #     handler def add(ctx, addend)
+    #       self.count += addend  # reads then writes via ctx.get/ctx.set
+    #     end
+    #
+    #     shared def get(ctx)
+    #       count  # reads via ctx.get, returns 0 if unset
+    #     end
+    #   end
+    def state(name, default: nil, serde: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      unless T.unsafe(self).respond_to?(:_service_kind) && %w[object workflow].include?(T.unsafe(self)._service_kind)
+        Kernel.raise ArgumentError, 'state declarations are only available on VirtualObject and Workflow'
+      end
+
+      name = name.to_sym
+      @_state_declarations[name] = { default: default, serde: serde }
+      state_key = name.to_s
+      state_serde = serde
+      state_default = default
+
+      # Getter: reads from durable state, returns default if unset
+      T.unsafe(self).define_method(name) do
+        ctx = Thread.current[:restate_context]
+        Kernel.raise 'Not inside a Restate handler' unless ctx
+
+        val = state_serde ? ctx.get(state_key, serde: state_serde) : ctx.get(state_key)
+        val.nil? ? state_default : val
+      end
+
+      # Setter: writes to durable state
+      T.unsafe(self).define_method(:"#{name}=") do |value|
+        ctx = Thread.current[:restate_context]
+        Kernel.raise 'Not inside a Restate handler' unless ctx
+
+        if state_serde
+          ctx.set(state_key, value, serde: state_serde)
+        else
+          ctx.set(state_key, value)
+        end
+      end
+
+      # Clear: removes the state entry
+      T.unsafe(self).define_method(:"clear_#{name}") do
+        ctx = Thread.current[:restate_context]
+        Kernel.raise 'Not inside a Restate handler' unless ctx
+
+        ctx.clear(state_key)
+      end
     end
 
     # Get or set the service name. Defaults to the unqualified class name.
@@ -210,8 +274,8 @@ module Restate
 
         um = T.unsafe(self).instance_method(name)
         arity = um.arity.abs
-        unless [1, 2].include?(arity)
-          Kernel.raise ArgumentError, "handler '#{name}' must accept 1 or 2 parameters (ctx[, input]), got #{arity}"
+        unless [0, 1].include?(arity)
+          Kernel.raise ArgumentError, "handler '#{name}' must accept 0 or 1 parameters ([input]), got #{arity}"
         end
 
         bound = um.bind(instance)

data/lib/restate/service_proxy.rb

@@ -0,0 +1,84 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # Proxy for fluent durable calls: +Service.call.handler(arg)+
+  #
+  # Returned by the +.call+ class method on service classes. Uses +method_missing+
+  # to forward handler invocations to the current Restate context.
+  #
+  # @example
+  #   # Instead of: ctx.service_call(Greeter, :greet, "World")
+  #   Greeter.call.greet("World")
+  #
+  #   # Instead of: ctx.object_call(Counter, :add, "key", 5)
+  #   Counter.call("key").add(5)
+  #
+  # @!visibility private
+  class ServiceCallProxy
+    extend T::Sig
+
+    sig { params(service_class: T.untyped, key: T.nilable(String), call_method: Symbol).void }
+    def initialize(service_class, key: nil, call_method: :service_call)
+      @service_class = service_class
+      @key = key
+      @call_method = call_method
+    end
+
+    def method_missing(handler_name, arg = nil, **opts)
+      ctx = Restate.fetch_context!
+      if @key
+        ctx.public_send(@call_method, @service_class, handler_name, @key, arg, **opts)
+      else
+        ctx.public_send(@call_method, @service_class, handler_name, arg, **opts)
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      (@service_class.respond_to?(:handlers) && T.unsafe(@service_class).handlers.key?(method_name.to_s)) || super
+    end
+  end
+
+  # Proxy for fluent fire-and-forget sends: +Service.send!.handler(arg)+
+  #
+  # Returned by the +.send!+ class method on service classes.
+  #
+  # @example
+  #   # Instead of: ctx.service_send(Greeter, :greet, "World")
+  #   Greeter.send!.greet("World")
+  #
+  #   # Instead of: ctx.object_send(Counter, :add, "key", 5, delay: 60)
+  #   Counter.send!("key", delay: 60).add(5)
+  #
+  # @!visibility private
+  class ServiceSendProxy
+    extend T::Sig
+
+    sig do
+      params(
+        service_class: T.untyped, key: T.nilable(String),
+        send_method: Symbol, delay: T.nilable(Numeric)
+      ).void
+    end
+    def initialize(service_class, key: nil, send_method: :service_send, delay: nil)
+      @service_class = service_class
+      @key = key
+      @send_method = send_method
+      @delay = delay
+    end
+
+    def method_missing(handler_name, arg = nil, **opts)
+      ctx = Restate.fetch_context!
+      opts[:delay] = @delay if @delay
+      if @key
+        ctx.public_send(@send_method, @service_class, handler_name, @key, arg, **opts)
+      else
+        ctx.public_send(@send_method, @service_class, handler_name, arg, **opts)
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      (@service_class.respond_to?(:handlers) && T.unsafe(@service_class).handlers.key?(method_name.to_s)) || super
+    end
+  end
+end

data/lib/restate/version.rb

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

data/lib/restate/virtual_object.rb

@@ -49,6 +49,30 @@ module Restate
       _register_handler(method_name, **T.unsafe({ kind: 'shared', **opts }))
     end
 
+    # Returns a call proxy for fluent durable calls to this virtual object.
+    #
+    # @example
+    #   Counter.call("my-key").add(5).await
+    #
+    # @param key [String] the object key
+    # @return [ServiceCallProxy]
+    def self.call(key)
+      ServiceCallProxy.new(self, key: key, call_method: :object_call)
+    end
+
+    # Returns a send proxy for fluent fire-and-forget sends to this virtual object.
+    #
+    # @example
+    #   Counter.send!("my-key").add(5)
+    #   Counter.send!("my-key", delay: 60).add(5)
+    #
+    # @param key [String] the object key
+    # @param delay [Numeric, nil] optional delay in seconds
+    # @return [ServiceSendProxy]
+    def self.send!(key, delay: nil)
+      ServiceSendProxy.new(self, key: key, send_method: :object_send, delay: delay)
+    end
+
     def self._service_kind
       'object'
     end

data/lib/restate/workflow.rb

@@ -49,6 +49,30 @@ module Restate
       _register_handler(method_name, **T.unsafe({ kind: 'shared', **opts }))
     end
 
+    # Returns a call proxy for fluent durable calls to this workflow.
+    #
+    # @example
+    #   UserSignup.call("user42").run("user@example.com").await
+    #
+    # @param key [String] the workflow key
+    # @return [ServiceCallProxy]
+    def self.call(key)
+      ServiceCallProxy.new(self, key: key, call_method: :workflow_call)
+    end
+
+    # Returns a send proxy for fluent fire-and-forget sends to this workflow.
+    #
+    # @example
+    #   UserSignup.send!("user42").run("user@example.com")
+    #   UserSignup.send!("user42", delay: 60).run("user@example.com")
+    #
+    # @param key [String] the workflow key
+    # @param delay [Numeric, nil] optional delay in seconds
+    # @return [ServiceSendProxy]
+    def self.send!(key, delay: nil)
+      ServiceSendProxy.new(self, key: key, send_method: :workflow_send, delay: delay)
+    end
+
     def self._service_kind
       'workflow'
     end