ruby-object-framework 1.0.0

data/lib/object_framework/execution.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module Values
+    # Storage values are immutable; domain state receives its own editable copy.
+    def self.mutable_copy(value)
+      case value
+      when String then value.dup
+      when Array then value.map { |item| mutable_copy(item) }
+      when Hash then value.to_h { |key, item| [mutable_copy(key), mutable_copy(item)] }
+      when Data then value.class.new(**mutable_copy(value.to_h))
+      else value
+      end
+    end
+
+    def self.detach(value, visiting = {})
+      composite = value.is_a?(Array) || value.is_a?(Hash) || value.is_a?(Data)
+      if composite
+        raise UnsafeResult, "Public values cannot contain cycles" if visiting.key?(value.object_id)
+        visiting[value.object_id] = true
+      end
+      case value
+      when nil, true, false, Symbol, Integer, Float then value
+      when String then value.dup.freeze
+      when Array then value.map { |item| detach(item, visiting) }.freeze
+      when Hash then value.to_h { |key, item| [detach(key, visiting), detach(item, visiting)] }.freeze
+      when Data then value.class.new(**detach(value.to_h, visiting))
+      else raise UnsafeResult, "Public results must contain independent values (#{value.class})"
+      end
+    ensure
+      visiting.delete(value.object_id) if composite
+    end
+  end
+
+  class Cancellation
+    def initialize(deadline: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @deadline, @clock, @mutex, @cancelled = deadline, clock, Mutex.new, false
+    end
+
+    def cancel
+      @mutex.synchronize { @cancelled = true }
+    end
+
+    def deadline
+      @mutex.synchronize { @deadline }
+    end
+
+    def deadline=(deadline)
+      @mutex.synchronize { @deadline = deadline }
+    end
+
+    def check!
+      raise Cancelled, "Operation cancelled" if @mutex.synchronize { @cancelled }
+      limit = deadline
+      raise DeadlineExceeded, "Deadline exceeded" if limit && @clock.call >= limit
+    end
+  end
+
+  class ExecutionContext
+    attr_reader :operation_id, :cancellation
+    attr_accessor :transaction_state
+
+    def initialize(cancellation: Cancellation.new)
+      @operation_id = SecureRandom.uuid.freeze
+      @cancellation, @started_at = cancellation, monotonic
+      @transaction_state, @failure_reported = :none, false
+      @mutex = Mutex.new
+    end
+
+    def elapsed
+      monotonic - @started_at
+    end
+
+    def claim_failure
+      @mutex.synchronize do
+        return false if @failure_reported
+        @failure_reported = true
+      end
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+
+  class Scope
+    def initialize(factories, context:)
+      @factories, @context, @instances, @resources = factories, context, { context: }, []
+    end
+
+    def provide(name, instance)
+      @instances[name] = instance
+    end
+
+    def resolve(name)
+      return @instances.fetch(name) if @instances.key?(name)
+      factory = @factories.fetch(name)
+      arguments = factory.dependencies.to_h { |dependency| [dependency, resolve(dependency)] }
+      instance = factory.build.call(**arguments)
+      @resources << instance if factory.close
+      @instances[name] = instance
+    end
+
+    def close(reporter:)
+      @resources.reverse_each do |resource|
+        resource.close
+      rescue StandardError => error
+        reporter.report(error, context: @context, secondary: true)
+      end
+      @resources.clear
+      @instances.clear
+    end
+  end
+
+  class Invocation
+    def initialize(operation:, factories:, storage:, reporter:, mappings: nil)
+      @operation, @factories, @storage, @reporter, @mappings = operation, factories, storage, reporter, mappings
+    end
+
+    def call(context: ExecutionContext.new, **arguments)
+      scope = Scope.new(@factories, context:)
+      transaction = session = nil
+      begin
+        context.cancellation.check!
+        if @operation.policy != :none
+          transaction = if @storage.respond_to?(:begin_transaction_for)
+            @storage.begin_transaction_for(mode: @operation.policy, context:)
+          else
+            @storage.begin_transaction(mode: @operation.policy)
+          end
+          context.transaction_state = :active
+          scope.provide(:transaction, transaction)
+          if @mappings
+            session = Persistence::Session.new(transaction:, mappings: @mappings)
+            scope.provide(:session, session)
+          end
+        end
+        dependencies = @operation.dependencies.to_h { |name| [name, scope.resolve(name)] }
+        use_case = @operation.use_case.new(**dependencies)
+        result = Values.detach(use_case.call(**arguments))
+        context.cancellation.check!
+        session&.flush
+        if transaction
+          context.transaction_state = :committing
+          transaction.commit
+        end
+        context.transaction_state = :committed if transaction
+        result
+      rescue StandardError => error
+        rollback(transaction, context:)
+        @reporter.report(error, context:)
+        raise
+      ensure
+        # Also release resources when a non-StandardError unwinds the request thread.
+        rollback(transaction, context:) if context.transaction_state == :active
+        session&.close
+        scope.close(reporter: @reporter)
+        close_transaction(transaction, context:)
+      end
+    end
+
+    private
+
+    def rollback(transaction, context:)
+      return unless transaction
+      state = transaction.respond_to?(:state) ? transaction.state : context.transaction_state
+      context.transaction_state = state == :committing ? :indeterminate : state
+      return unless state == :active
+      transaction.rollback
+      context.transaction_state = :rolled_back
+    rescue StandardError => error
+      context.transaction_state = :indeterminate
+      @reporter.report(error, context:, secondary: true)
+    end
+
+    def close_transaction(transaction, context:)
+      transaction&.close
+    rescue StandardError => error
+      @reporter.report(error, context:, secondary: true)
+    end
+  end
+end

data/lib/object_framework/grpc/messages.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module GRPC
+    class Unimplemented < StandardError; end
+
+    class Messages
+      include Enumerable
+
+      def self.frame(bytes)
+        [0, bytes.bytesize].pack("CN") + bytes.b
+      end
+
+      def initialize(input:, descriptor:, message_limit: 1024 * 1024)
+        @input, @descriptor, @limit = input, descriptor, message_limit
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+        while (header = @input.read_exact(5, allow_eof: true))
+          compressed, length = header.unpack("CN")
+          raise InvalidInput, "Invalid gRPC compression flag" unless [0, 1].include?(compressed)
+          raise Unimplemented, "Message compression is not supported" if compressed == 1
+          raise CapacityExceeded, "Message exceeds configured limit" if length > @limit
+          yield @descriptor.decode(@input.read_exact(length))
+        end
+      end
+    end
+  end
+end

data/lib/object_framework/grpc/server.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module GRPC
+    class Controller
+      def initialize(application:, operation:)
+        @application, @operation = application, operation
+      end
+
+      def call(input, context:)
+        @application.invoke(@operation, context:, **input)
+      end
+
+      def validate!
+        @application.validate_operation!(@operation)
+      end
+    end
+
+    class StatusPresenter
+      STATUSES = { bad_request: 3, invalid_input: 3, unauthenticated: 16, forbidden: 7,
+        not_found: 5, conflict: 9, duplicate: 6, transaction_conflict: 10,
+        rate_limited: 8, capacity: 8, unavailable: 14, deadline: 4, cancelled: 1,
+        unimplemented: 12, internal: 13 }.freeze
+
+      def initialize(registry:); @registry = registry; end
+
+      def call(error)
+        description = @registry.resolve(error)
+        [STATUSES.fetch(description.category), description.code, description.title]
+      end
+    end
+
+    class Call
+      def initialize(connection:, stream:, descriptor:, message_limit:)
+        @connection, @stream, @descriptor, @limit = connection, stream, descriptor, message_limit
+        @started = false
+      end
+
+      def send(value)
+        @stream.context.cancellation.check!
+        payload = @descriptor.encode(value)
+        raise CapacityExceeded, "Message exceeds configured limit" if payload.bytesize > @limit
+        unless @started
+          @connection.send_headers(@stream, initial_headers)
+          @started = true
+        end
+        @connection.send_data(@stream, Messages.frame(payload))
+      end
+
+      def finish(status: 0, code: "ok", message: "")
+        return if @connection.reset?(@stream)
+        trailers = [["grpc-status", status.to_s], ["error-code", code], ["operation-id", @stream.context.operation_id]]
+        trailers << ["grpc-message", escape(message)] unless message.empty?
+        trailers = initial_headers + trailers unless @started
+        @connection.send_headers(@stream, trailers, end_stream: true)
+      end
+
+      private
+
+      def initial_headers
+        [[":status", "200"], ["content-type", "application/grpc"], ["grpc-accept-encoding", "identity"], ["operation-id", @stream.context.operation_id]]
+      end
+
+      def escape(value)
+        value.b.bytes.map { |byte| byte.between?(32, 126) && byte != 37 ? byte.chr : format("%%%02X", byte) }.join
+      end
+    end
+
+    class Server
+      attr_reader :name, :port
+
+      def initialize(application:, services:, controllers:, host: "127.0.0.1", port: 0,
+                     name: :grpc, max_requests: 128, max_connections: 128,
+                     message_limit: 1024 * 1024, header_limit: 32 * 1024,
+                     execution_timeout: 30, idle_timeout: 30, shutdown_timeout: 5,
+                     tls_context: nil, status_presenter: nil)
+        @application, @services, @controllers, @host, @port, @name = application, services.dup, controllers.dup, host, port, name
+        @max_requests, @max_connections, @message_limit, @header_limit = max_requests, max_connections, message_limit, header_limit
+        @execution_timeout, @idle_timeout, @shutdown_timeout, @tls_context = execution_timeout, idle_timeout, shutdown_timeout, tls_context
+        @presenter = status_presenter || StatusPresenter.new(registry: application.errors)
+        @mutex, @workers, @connections, @routes = Mutex.new, {}, {}.compare_by_identity, {}
+      end
+
+      def requires; []; end
+
+      def configure(application)
+        application.errors.register(Unimplemented, category: :unimplemented, code: "rpc_unimplemented", title: "RPC method not implemented")
+        application.errors.register(HTTP2::ProtocolError, category: :bad_request, code: "http2_protocol_error", title: "Invalid HTTP/2 request")
+        application.errors.register(HTTP2::CompressionError, category: :bad_request, code: "hpack_error", title: "Invalid compressed headers")
+      end
+
+      def validate!
+        unless [@max_requests, @max_connections, @message_limit, @header_limit].all? { |value| value.is_a?(Integer) && value.positive? }
+          raise ConfigurationError, "gRPC limits must be positive integers"
+        end
+        unless [@execution_timeout, @idle_timeout, @shutdown_timeout].all? { |value| value.is_a?(Numeric) && value.positive? }
+          raise ConfigurationError, "gRPC timeouts must be positive"
+        end
+        @services.each do |service|
+          service.methods.each_value do |method|
+            controller = @controllers.fetch(method.controller) { raise ConfigurationError, "Missing RPC controller" }
+            raise ConfigurationError, "RPC controllers must implement call" unless controller.respond_to?(:call)
+            controller.validate! if controller.respond_to?(:validate!)
+            path = "/#{service.name}/#{method.name}"
+            raise ConfigurationError, "Duplicate RPC route" if @routes.key?(path)
+            @routes[path] = method
+          end
+          service.finalize!
+        end
+        @routes.freeze
+        @controllers.freeze
+        @services.freeze
+        if @tls_context
+          raise ConfigurationError, "TLS requires a certificate and private key" unless @tls_context.cert && @tls_context.key
+          @tls_context.alpn_select_cb = ->(protocols) { protocols.include?("h2") ? "h2" : raise(HTTP2::ProtocolError, "h2 required") }
+          @tls_context.setup
+        end
+      end
+
+      def start
+        @listener = TCPServer.new(@host, @port)
+        @port = @listener.local_address.ip_port
+        @wake_reader, @wake_writer = IO.pipe
+        @running = true
+        @acceptor = Thread.new { accept_connections }
+        self
+      end
+
+      def active_count; @mutex.synchronize { @workers.size }; end
+
+      def stop
+        return unless @acceptor
+        @running = false
+        @wake_writer.write_nonblock(".", exception: false)
+        @acceptor.join
+        connections, workers = @mutex.synchronize do
+          @workers.each_value { |stream| stream.context.cancellation.cancel }
+          [@connections.to_a, @workers.keys]
+        end
+        connections.each { |connection, _| connection.close }
+        deadline = HTTP::Timing.now + @shutdown_timeout
+        (workers + connections.map(&:last)).each { |thread| thread.join([deadline - HTTP::Timing.now, 0].max) }
+        @listener.close
+        @wake_reader.close
+        @wake_writer.close
+        @acceptor = nil
+      end
+
+      private
+
+      def accept_connections
+        while @running
+          readable = IO.select([@listener, @wake_reader])&.first
+          break if !@running || readable.include?(@wake_reader)
+          loop do
+            socket = @listener.accept_nonblock(exception: false)
+            break if socket == :wait_readable
+            @mutex.synchronize do
+              if @connections.size >= @max_connections
+                socket.close
+                next
+              end
+              io = @tls_context ? OpenSSL::SSL::SSLSocket.new(socket, @tls_context) : socket
+              io.sync_close = true if @tls_context
+              connection = HTTP2::Connection.new(io:, on_stream: method(:admit), reporter: @application.reporter,
+                stream_limit: @max_requests, header_limit: @header_limit, idle_timeout: @idle_timeout, tls: !!@tls_context)
+              thread = Thread.new do
+                begin
+                  connection.run
+                ensure
+                  @mutex.synchronize { @connections.delete(connection) }
+                end
+              end
+              @connections[connection] = thread
+            end
+          end
+        end
+      end
+
+      def admit(connection, stream, headers)
+        metadata = headers.to_h
+        context = stream.context
+        set_deadline(context, metadata["grpc-timeout"])
+        unless metadata[":method"] == "POST" && metadata.fetch("content-type", "").match?(/\Aapplication\/grpc(?:\+proto)?(?:;.*)?\z/)
+          connection.send_headers(stream, [[":status", "415"]], end_stream: true)
+          return
+        end
+        method = @routes[metadata[":path"]]
+        unless method
+          fail_call(connection, stream, Unimplemented.new)
+          return
+        end
+        admitted = @mutex.synchronize do
+          if @workers.size >= @max_requests
+            false
+          else
+            thread = Thread.new { perform(connection, stream, method) }
+            @workers[thread] = stream
+            true
+          end
+        end
+        fail_call(connection, stream, CapacityExceeded.new) unless admitted
+      rescue StandardError => error
+        fail_call(connection, stream, error)
+      end
+
+      def perform(connection, stream, method)
+        call = Call.new(connection:, stream:, descriptor: method.output, message_limit: @message_limit)
+        messages = Messages.new(input: stream.input, descriptor: method.input, message_limit: @message_limit)
+        begin
+          input = method.client_streaming ? messages : single_message(messages)
+          result = @controllers.fetch(method.controller).call(input, context: stream.context)
+          if method.server_streaming
+            result.each { |value| call.send(value) }
+          else
+            call.send(result)
+          end
+          call.finish
+        rescue StandardError => error
+          fail_call(connection, stream, error, call:)
+        ensure
+          @mutex.synchronize { @workers.delete(Thread.current) }
+        end
+      end
+
+      def single_message(messages)
+        value = nil
+        count = 0
+        messages.each do |message|
+          count += 1
+          raise InvalidInput, "Unary RPC requires exactly one message" if count > 1
+          value = message
+        end
+        raise InvalidInput, "Unary RPC requires exactly one message" unless count == 1
+        value
+      end
+
+      def fail_call(connection, stream, error, call: nil)
+        @application.reporter.report(error, context: stream.context)
+        begin
+          status, code, message = @presenter.call(error)
+        rescue StandardError => secondary
+          @application.reporter.report(secondary, context: stream.context, secondary: true)
+          status, code, message = 13, "internal_error", "Internal server error"
+        end
+        call ||= Call.new(connection:, stream:, descriptor: nil, message_limit: @message_limit)
+        call.finish(status:, code:, message:)
+      rescue StandardError => secondary
+        @application.reporter.report(secondary, context: stream.context, secondary: true)
+      end
+
+      def set_deadline(context, value)
+        timeout = @execution_timeout
+        if value
+          match = /\A([0-9]{1,8})([HMSmun])\z/.match(value)
+          raise InvalidInput, "Invalid gRPC timeout" unless match
+          units = { "H" => 3600, "M" => 60, "S" => 1, "m" => 0.001, "u" => 0.000001, "n" => 0.000000001 }
+          timeout = [timeout, Integer(match[1], 10) * units.fetch(match[2])].min
+        end
+        context.cancellation.deadline = HTTP::Timing.now + timeout
+      end
+    end
+  end
+end

data/lib/object_framework/grpc/service.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module GRPC
+    Method = Data.define(:name, :input, :output, :controller, :client_streaming, :server_streaming)
+
+    class Service
+      attr_reader :name, :methods
+
+      def initialize(name)
+        parts = name.to_s.split(".", -1)
+        raise ConfigurationError, "Invalid service name" if parts.empty?
+        parts.each { |part| Protobuf.name(part) }
+        @name, @methods = name.to_s.dup.freeze, {}
+      end
+
+      def rpc(name, input:, output:, controller:, client_streaming: false, server_streaming: false)
+        raise ConfigurationError, "Service is finalized" if @methods.frozen?
+        name = Protobuf.name(name)
+        raise ConfigurationError, "Duplicate RPC method" if @methods.key?(name)
+        raise ConfigurationError, "RPC contracts require message descriptors" unless input.is_a?(Protobuf::Message) && output.is_a?(Protobuf::Message)
+        @methods[name] = Method.new(name:, input:, output:, controller:, client_streaming:, server_streaming:)
+        self
+      end
+
+      def finalize!
+        to_proto
+        @methods.freeze
+        freeze
+      end
+
+      def to_proto
+        definitions = {}
+        visit = lambda do |type|
+          if definitions.key?(type.name)
+            raise ConfigurationError, "Ambiguous protobuf type name: #{type.name}" unless definitions[type.name].equal?(type)
+            return
+          end
+          definitions[type.name] = type
+          type.dependencies.each { |child| visit.call(child) } if type.is_a?(Protobuf::Message)
+        end
+        @methods.each_value { |method| visit.call(method.input); visit.call(method.output) }
+        package = name.split(".")[0...-1].join(".")
+        output = "syntax = \"proto3\";\n"
+        output += "package #{package};\n" unless package.empty?
+        output += "\n" + definitions.values.map(&:definition).join("\n")
+        output += "\nservice #{name.split('.').last} {\n"
+        @methods.each_value do |method|
+          output += "  rpc #{method.name} (#{method.client_streaming ? 'stream ' : ''}#{method.input.name}) returns (#{method.server_streaming ? 'stream ' : ''}#{method.output.name});\n"
+        end
+        output + "}\n"
+      end
+    end
+  end
+end

data/lib/object_framework/http/io.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "time"
+
+module ObjectFramework
+  module HTTP
+    module Timing
+      def self.now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def self.wait(io, mode, deadline)
+        remaining = deadline - now
+        raise RequestTimeout if remaining <= 0
+        readable, writable = mode == :read ? [[io], nil] : [nil, [io]]
+        raise RequestTimeout unless IO.select(readable, writable, nil, remaining)
+      end
+    end
+
+    class Reader
+      attr_reader :io, :buffer, :waiter
+
+      def initialize(io:, buffer: +"".b, waiter: nil)
+        @io, @buffer = io, buffer
+        @waiter = waiter || ->(mode, deadline) { Timing.wait(io, mode, deadline) }
+      end
+
+      def read_head(parser, header_timeout:, idle_timeout:, idle: false)
+        started = !idle || !buffer.empty?
+        deadline = Timing.now + (started ? header_timeout : idle_timeout)
+        loop do
+          first_line = buffer.index("\r\n")
+          raise URITooLong if (first_line || buffer.bytesize) > parser.line_limit
+          if (finish = buffer.index("\r\n\r\n"))
+            return parser.parse_head(buffer.slice!(0, finish + 4))
+          end
+          raise HeadersTooLarge if first_line && buffer.bytesize - first_line - 2 > parser.header_limit
+          buffer << read_chunk(deadline:)
+          unless started
+            started, deadline = true, Timing.now + header_timeout
+          end
+        end
+      rescue RequestTimeout
+        raise EOFError if idle && !started
+        raise
+      rescue EOFError
+        raise BadRequest unless buffer.empty?
+        raise
+      end
+
+      def read_exact(count, deadline:)
+        buffer << read_chunk(deadline:) while buffer.bytesize < count
+        buffer.slice!(0, count)
+      end
+
+      def read_line(limit:, deadline:)
+        loop do
+          if (finish = buffer.index("\r\n"))
+            raise HeadersTooLarge if finish > limit
+            return buffer.slice!(0, finish + 2).delete_suffix("\r\n")
+          end
+          raise HeadersTooLarge if buffer.bytesize > limit
+          buffer << read_chunk(deadline:)
+        end
+      end
+
+      def write(bytes, deadline:)
+        offset = 0
+        while offset < bytes.bytesize
+          raise RequestTimeout if Timing.now >= deadline
+          result = io.write_nonblock(bytes.byteslice(offset..), exception: false)
+          case result
+          when :wait_readable then waiter.call(:read, deadline)
+          when :wait_writable then waiter.call(:write, deadline)
+          else
+            offset += result
+            yield result if block_given?
+          end
+        end
+      end
+
+      private
+
+      def read_chunk(deadline:)
+        loop do
+          raise RequestTimeout if Timing.now >= deadline
+          result = io.read_nonblock(16_384, exception: false)
+          case result
+          when :wait_readable then waiter.call(:read, deadline)
+          when :wait_writable then waiter.call(:write, deadline)
+          when nil then raise EOFError
+          else return result
+          end
+        end
+      end
+    end
+
+    class Writer
+      REASONS = { 200 => "OK", 204 => "No Content", 400 => "Bad Request", 401 => "Unauthorized",
+        403 => "Forbidden", 404 => "Not Found", 405 => "Method Not Allowed", 408 => "Request Timeout",
+        409 => "Conflict", 413 => "Content Too Large", 414 => "URI Too Long", 415 => "Unsupported Media Type",
+        417 => "Expectation Failed", 422 => "Unprocessable Content", 429 => "Too Many Requests",
+        431 => "Request Header Fields Too Large", 500 => "Internal Server Error", 501 => "Not Implemented",
+        503 => "Service Unavailable", 505 => "HTTP Version Not Supported" }.freeze
+      attr_reader :started
+
+      def initialize(reader:)
+        @reader, @started = reader, false
+      end
+
+      def call(response, head: false, keep_alive: true, deadline:)
+        status, body = response.status, response.body
+        raise InvalidInput, "Invalid response status" unless status.is_a?(Integer) && status.between?(200, 599)
+        headers = response.headers.reject { |name, _| %w[date connection content-length].include?(name.downcase) }
+        headers = headers.merge("Date" => Time.now.httpdate, "Connection" => keep_alive ? "keep-alive" : "close")
+        headers["Content-Length"] = body.bytesize.to_s unless [204, 304].include?(status)
+        headers.each do |name, value|
+          raise InvalidInput, "Invalid response header" unless Parser::TOKEN.match?(name) && !value.to_s.match?(/[\x00-\x1f\x7f]/)
+          raise InvalidInput, "Response transfer encodings are not supported" if name.downcase == "transfer-encoding"
+        end
+        prefix = "HTTP/1.1 #{status} #{REASONS.fetch(status, 'Response')}\r\n" + headers.map { |key, value| "#{key}: #{value}\r\n" }.join + "\r\n"
+        bytes = head || [204, 304].include?(status) ? prefix : prefix + body
+        @reader.write(bytes, deadline:) { @started = true }
+      end
+    end
+  end
+end