restate-sdk 0.4.3

data/lib/restate/service.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # A stateless Restate service.
+  #
+  # @example
+  #   class Greeter < Restate::Service
+  #     handler def greet(name)
+  #       "Hello, #{name}!"
+  #     end
+  #   end
+  class Service
+    extend T::Sig
+    extend ServiceDSL
+
+    # Register a handler method on this service.
+    # Use as: +handler def my_method(arg)+ or +handler :my_method, 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.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: nil, **opts }))
+    end
+
+    def self._service_kind
+      'service'
+    end
+  end
+end

data/lib/restate/service_dsl.rb

@@ -0,0 +1,243 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # Shared class-level DSL for defining Restate services via class inheritance.
+  #
+  # Extended into Service, VirtualObject, and Workflow. Provides the +handler+,
+  # +shared+, +main+, and +service_name+ class macros.
+  #
+  # @example
+  #   class Counter < Restate::VirtualObject
+  #     handler def add(addend)
+  #       ctx = Restate.current_object_context
+  #       old = ctx.get('counter') || 0
+  #       ctx.set('counter', old + addend)
+  #       old + addend
+  #     end
+  #   end
+  module ServiceDSL # rubocop:disable Metrics/ModuleLength
+    # Called when a subclass is created; initializes the handler registry.
+    def inherited(subclass) # rubocop:disable Metrics/MethodLength
+      super
+      subclass.instance_variable_set(:@_handler_registry, {})
+      subclass.instance_variable_set(:@_service_name, nil)
+      subclass.instance_variable_set(:@_handlers, nil)
+      subclass.instance_variable_set(:@_enable_lazy_state, nil)
+      subclass.instance_variable_set(:@_description, nil)
+      subclass.instance_variable_set(:@_metadata, nil)
+      subclass.instance_variable_set(:@_inactivity_timeout, nil)
+      subclass.instance_variable_set(:@_abort_timeout, nil)
+      subclass.instance_variable_set(:@_journal_retention, nil)
+      subclass.instance_variable_set(:@_idempotency_retention, nil)
+      subclass.instance_variable_set(:@_ingress_private, nil)
+      subclass.instance_variable_set(:@_invocation_retry_policy, nil)
+    end
+
+    # Get or set the service name. Defaults to the unqualified class name.
+    #
+    # @param name [String, nil] when provided, sets the service name
+    # @return [String] the current service name
+    def service_name(name = nil)
+      if name
+        @_service_name = name
+      else
+        @_service_name || T.unsafe(self).name&.split('::')&.last
+      end
+    end
+
+    # Enable lazy state loading for all handlers in this service.
+    # When enabled, state is fetched on demand rather than pre-loaded.
+    #
+    # @param value [Boolean] whether to enable lazy state
+    def enable_lazy_state(value = true) # rubocop:disable Style/OptionalBooleanParameter
+      @_enable_lazy_state = value
+    end
+
+    # Set or get a human-readable description for this service.
+    #
+    # @param text [String, nil] when provided, sets the description
+    # @return [String, nil] the current description
+    def description(text = nil)
+      if text
+        @_description = text
+      else
+        @_description
+      end
+    end
+
+    # Set or get metadata for this service.
+    #
+    # @param hash [Hash, nil] when provided, sets the metadata
+    # @return [Hash, nil] the current metadata
+    def metadata(hash = nil)
+      if hash
+        @_metadata = hash
+      else
+        @_metadata
+      end
+    end
+
+    # Set the inactivity timeout (in seconds) for this service.
+    #
+    # @param seconds [Numeric] timeout in seconds
+    def inactivity_timeout(seconds)
+      @_inactivity_timeout = seconds
+    end
+
+    # Set the abort timeout (in seconds) for this service.
+    #
+    # @param seconds [Numeric] timeout in seconds
+    def abort_timeout(seconds)
+      @_abort_timeout = seconds
+    end
+
+    # Set the journal retention (in seconds) for this service.
+    #
+    # @param seconds [Numeric] retention in seconds
+    def journal_retention(seconds)
+      @_journal_retention = seconds
+    end
+
+    # Set the idempotency retention (in seconds) for this service.
+    #
+    # @param seconds [Numeric] retention in seconds
+    def idempotency_retention(seconds)
+      @_idempotency_retention = seconds
+    end
+
+    # Mark this service as private to the ingress.
+    #
+    # @param value [Boolean] whether the service is ingress-private
+    def ingress_private(value = true) # rubocop:disable Style/OptionalBooleanParameter
+      @_ingress_private = value
+    end
+
+    # Set the invocation retry policy for this service.
+    #
+    # @param initial_interval [Numeric, nil] initial retry interval in seconds
+    # @param max_interval [Numeric, nil] maximum retry interval in seconds
+    # @param max_attempts [Integer, nil] maximum number of retry attempts
+    # @param exponentiation_factor [Numeric, nil] backoff exponentiation factor
+    # @param on_max_attempts [Symbol, String, nil] action on max attempts (:pause or :kill)
+    def invocation_retry_policy(initial_interval: nil, max_interval: nil, max_attempts: nil,
+                                exponentiation_factor: nil, on_max_attempts: nil)
+      @_invocation_retry_policy = {
+        initial_interval: initial_interval,
+        max_interval: max_interval,
+        max_attempts: max_attempts,
+        exponentiation_factor: exponentiation_factor,
+        on_max_attempts: on_max_attempts
+      }.compact
+    end
+
+    # Returns the ServiceTag for this class-based service.
+    # Subclasses must define +_service_kind+.
+    #
+    # @return [ServiceTag]
+    def service_tag
+      ServiceTag.new(kind: T.unsafe(self)._service_kind, name: service_name,
+                     description: @_description, metadata: @_metadata)
+    end
+
+    # Returns the service-level lazy state setting (nil if not set).
+    def lazy_state?
+      @_enable_lazy_state
+    end
+
+    # Returns the service-level inactivity timeout (nil if not set).
+    def svc_inactivity_timeout
+      @_inactivity_timeout
+    end
+
+    # Returns the service-level abort timeout (nil if not set).
+    def svc_abort_timeout
+      @_abort_timeout
+    end
+
+    # Returns the service-level journal retention (nil if not set).
+    def svc_journal_retention
+      @_journal_retention
+    end
+
+    # Returns the service-level idempotency retention (nil if not set).
+    def svc_idempotency_retention
+      @_idempotency_retention
+    end
+
+    # Returns the service-level ingress private setting (nil if not set).
+    def svc_ingress_private
+      @_ingress_private
+    end
+
+    # Returns the service-level invocation retry policy (nil if not set).
+    def svc_invocation_retry_policy
+      @_invocation_retry_policy
+    end
+
+    # Returns a hash of handler name (String) to Handler.
+    # Built lazily on first access and cached.
+    #
+    # @return [Hash{String => Handler}]
+    def handlers
+      @_handlers ||= _build_handlers # rubocop:disable Naming/MemoizedInstanceVariableName
+    end
+
+    private
+
+    # Store handler metadata for later building.
+    def _register_handler(method_name, kind:, **opts)
+      @_handlers = nil # invalidate cache
+      @_handler_registry[method_name.to_s] = { kind: kind, **opts }
+      method_name
+    end
+
+    # Build Handler structs from the registry using instance_method + bind.
+    def _build_handlers # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      tag = service_tag
+      result = {}
+      instance = T.unsafe(self).allocate
+
+      @_handler_registry.each do |name, meta| # rubocop:disable Metrics/BlockLength
+        input_serde = Serde.resolve(meta[:input])
+        output_serde = Serde.resolve(meta[:output])
+
+        handler_io = HandlerIO.new(
+          accept: meta[:accept] || 'application/json',
+          content_type: meta[:content_type] || 'application/json',
+          input_serde: input_serde,
+          output_serde: output_serde
+        )
+
+        um = T.unsafe(self).instance_method(name)
+        arity = um.arity.abs
+        unless [0, 1].include?(arity)
+          Kernel.raise ArgumentError, "handler '#{name}' must accept 0 or 1 parameters ([input]), got #{arity}"
+        end
+
+        bound = um.bind(instance)
+
+        result[name] = Handler.new(
+          service_tag: tag,
+          handler_io: handler_io,
+          kind: meta[:kind],
+          name: name,
+          callable: bound,
+          arity: arity,
+          enable_lazy_state: meta[:enable_lazy_state],
+          description: meta[:description],
+          metadata: meta[:metadata],
+          inactivity_timeout: meta[:inactivity_timeout],
+          abort_timeout: meta[:abort_timeout],
+          journal_retention: meta[:journal_retention],
+          idempotency_retention: meta[:idempotency_retention],
+          workflow_completion_retention: meta[:workflow_completion_retention],
+          ingress_private: meta[:ingress_private],
+          invocation_retry_policy: meta[:invocation_retry_policy]
+        )
+      end
+
+      result
+    end
+  end
+end

data/lib/restate/testing.rb

@@ -0,0 +1,197 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'restate'
+require 'socket'
+require 'net/http'
+require 'json'
+require 'uri'
+require 'testcontainers'
+
+module Restate
+  # Test harness for running Restate services with a real Restate server.
+  # Opt-in via `require "restate/testing"` (not loaded by default).
+  #
+  # Requires Docker and the testcontainers-core gem.
+  #
+  # Block-based (recommended):
+  #   Restate::Testing.start(Greeter, Counter) do |env|
+  #     env.ingress_url  # => "http://localhost:32771"
+  #     env.admin_url    # => "http://localhost:32772"
+  #   end
+  #
+  # Manual lifecycle (for RSpec before/after hooks):
+  #   harness = Restate::Testing::RestateTestHarness.new(Greeter, Counter)
+  #   harness.start
+  #   harness.ingress_url
+  #   harness.stop
+  module Testing
+    # Starts a Restate test environment with the given services.
+    # When a block is given, stops automatically on block exit.
+    # Without a block, returns the harness for manual lifecycle management.
+    def self.start(*services, **options)
+      harness = RestateTestHarness.new(*services, **options)
+      harness.start
+
+      if block_given?
+        begin
+          yield harness
+        ensure
+          harness.stop
+        end
+      else
+        harness
+      end
+    end
+
+    # Manages the lifecycle of an SDK server and a Restate container for testing.
+    class RestateTestHarness
+      attr_reader :ingress_url, :admin_url
+
+      # @param services [Array<Class>] Service classes to register.
+      # @param restate_image [String] Docker image for Restate server.
+      # @param always_replay [Boolean] Force replay on every suspension point.
+      # @param disable_retries [Boolean] Disable Restate retry policy.
+      def initialize(*services,
+                     restate_image: 'docker.io/restatedev/restate:latest',
+                     always_replay: false,
+                     disable_retries: false)
+        @services = services
+        @restate_image = restate_image
+        @always_replay = always_replay
+        @disable_retries = disable_retries
+        @server_thread = nil
+        @container = nil
+        @port = nil
+        @ingress_url = nil
+        @admin_url = nil
+      end
+
+      def start
+        @port = find_free_port
+        rack_app = Restate.endpoint(*@services).app
+        start_sdk_server(rack_app)
+        wait_for_tcp(@port)
+        start_restate_container
+        register_sdk
+        self
+      rescue StandardError => e
+        stop
+        raise e
+      end
+
+      def stop
+        stop_restate_container
+        stop_sdk_server
+      end
+
+      private
+
+      def find_free_port
+        server = TCPServer.new('0.0.0.0', 0)
+        port = server.addr[1]
+        server.close
+        port
+      end
+
+      def start_sdk_server(rack_app)
+        require 'async'
+        require 'async/http/endpoint'
+        require 'falcon/server'
+
+        port = @port
+        ready = Queue.new
+
+        @server_thread = Thread.new do
+          Async do
+            endpoint = Async::HTTP::Endpoint.parse("http://0.0.0.0:#{port}")
+            middleware = Falcon::Server.middleware(rack_app, cache: false)
+            server = Falcon::Server.new(middleware, endpoint)
+            ready.push(true)
+            server.run
+          end
+        end
+
+        ready.pop
+      end
+
+      def wait_for_tcp(port, timeout: 10)
+        deadline = Time.now + timeout
+        loop do
+          TCPSocket.new('127.0.0.1', port).close
+          return
+        rescue Errno::ECONNREFUSED, Errno::ECONNRESET
+          raise "SDK server failed to start on port #{port} within #{timeout}s" if Time.now > deadline
+
+          sleep 0.1
+        end
+      end
+
+      def start_restate_container
+        env = {
+          'RESTATE_LOG_FILTER' => 'restate=info',
+          'RESTATE_BOOTSTRAP_NUM_PARTITIONS' => '1',
+          'RESTATE_DEFAULT_NUM_PARTITIONS' => '1',
+          'RESTATE_SHUTDOWN_TIMEOUT' => '10s',
+          'RESTATE_ROCKSDB_TOTAL_MEMORY_SIZE' => '32 MB',
+          'RESTATE_WORKER__INVOKER__IN_MEMORY_QUEUE_LENGTH_LIMIT' => '64',
+          'RESTATE_WORKER__INVOKER__INACTIVITY_TIMEOUT' => @always_replay ? '0s' : '10m',
+          'RESTATE_WORKER__INVOKER__ABORT_TIMEOUT' => '10m'
+        }
+        env['RESTATE_WORKER__INVOKER__RETRY_POLICY__TYPE'] = 'none' if @disable_retries
+
+        @container = RestateContainer.new(@restate_image)
+        @container.with_exposed_ports(8080, 9070)
+        @container.with_env(env)
+        @container.start
+
+        @container.wait_for_http(path: '/restate/health', container_port: 8080, status: 200, timeout: 30)
+        @container.wait_for_http(path: '/health', container_port: 9070, status: 200, timeout: 30)
+
+        @ingress_url = "http://#{@container.host}:#{@container.mapped_port(8080)}"
+        @admin_url = "http://#{@container.host}:#{@container.mapped_port(9070)}"
+      end
+
+      def register_sdk
+        uri = URI("#{@admin_url}/deployments")
+        sdk_url = "http://host.docker.internal:#{@port}"
+
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        request.body = JSON.generate({ uri: sdk_url })
+
+        response = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(request) }
+        return if response.code.start_with?('2')
+
+        raise "Failed to register SDK at #{sdk_url}: #{response.code} #{response.body}"
+      end
+
+      def stop_restate_container
+        return unless @container
+
+        @container.stop!
+        @container.remove(force: true)
+      rescue StandardError
+        # Ignore cleanup errors
+      end
+
+      def stop_sdk_server
+        @server_thread&.kill
+        @server_thread&.join(5)
+      end
+    end
+
+    # Testcontainers::DockerContainer subclass that adds ExtraHosts support
+    # so the Restate container can reach the host-bound SDK server.
+    class RestateContainer < Testcontainers::DockerContainer
+      private
+
+      def _container_create_options
+        options = super
+        options['HostConfig'] ||= {}
+        options['HostConfig']['ExtraHosts'] = ['host.docker.internal:host-gateway']
+        options
+      end
+    end
+  end
+end

data/lib/restate/version.rb

@@ -0,0 +1,6 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Restate
+  VERSION = '0.4.3'
+end

data/lib/restate/virtual_object.rb

@@ -0,0 +1,58 @@
+# typed: true
+# frozen_string_literal: true
+
+module Restate
+  # A keyed virtual object with durable state.
+  #
+  # @example
+  #   class Counter < Restate::VirtualObject
+  #     handler def add(addend)
+  #       ctx = Restate.current_object_context
+  #       old = ctx.get("count") || 0
+  #       ctx.set("count", old + addend)
+  #       old + addend
+  #     end
+  #
+  #     shared def get
+  #       ctx = Restate.current_object_context
+  #       ctx.get("count") || 0
+  #     end
+  #   end
+  class VirtualObject
+    extend T::Sig
+    extend ServiceDSL
+
+    # Register an exclusive handler. Use as: +handler def my_method(arg)+
+    #
+    # @param method_name [Symbol] name of the method to register
+    # @param kind [Symbol] concurrency mode (+:exclusive+ or +:shared+)
+    # @param opts [Hash] handler options (+input:+, +output:+, +accept:+, +content_type:+)
+    # @return [Symbol] the method name
+    def self.handler(method_name = nil, kind: :exclusive, **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: kind.to_s, **opts }))
+    end
+
+    # Register a shared (concurrent-access) handler.
+    #
+    # @param method_name [Symbol] name of the method to register
+    # @return [Symbol] the method name
+    def self.shared(method_name, **opts)
+      if method_name.is_a?(String)
+        raise ArgumentError,
+              "handler expects a Symbol (use `shared def #{method_name}(...)` or `shared :#{method_name}`)"
+      end
+
+      _register_handler(method_name, **T.unsafe({ kind: 'shared', **opts }))
+    end
+
+    def self._service_kind
+      'object'
+    end
+  end
+end