ruby-object-framework 1.0.0

data/examples/guides/11_ractor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+class SumNumbers
+  def self.call(input)
+    { total: input[:numbers].sum }
+  end
+end
+
+owner = Thread.current.object_id
+task = ObjectFramework::Capabilities::IsolatedTask.new(task: SumNumbers)
+result = task.call({ numbers: [1, 2, 3] })
+puts "Total: #{result[:total]}"
+puts "Request thread preserved: #{Thread.current.object_id == owner}"

data/examples/guides/12_box.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+first = ObjectFramework::Capabilities::Definitions.new
+second = ObjectFramework::Capabilities::Definitions.new
+first.evaluate("class Name; def self.call; 'first application'; end; end")
+second.evaluate("class Name; def self.call; 'second application'; end; end")
+puts first.constant(:Name).call
+puts second.constant(:Name).call
+puts "Definitions leaked: #{Object.const_defined?(:Name)}"

data/examples/guides/13_testing.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../../test/support/spec"
+
+class PriceWithTax
+  def call(cents:)
+    raise ArgumentError, "Price must be nonnegative" if cents.negative?
+    cents + cents / 5
+  end
+end
+
+Spec.test "a zero price remains zero" do
+  assert_equal 0, PriceWithTax.new.call(cents: 0)
+end
+
+Spec.test "a price includes twenty percent tax" do
+  assert_equal 1200, PriceWithTax.new.call(cents: 1000)
+end
+
+Spec.test "negative prices are rejected" do
+  assert_raises(ArgumentError) { PriceWithTax.new.call(cents: -1) }
+end
+
+exit Spec.run

data/examples/guides/manifest.yml

@@ -0,0 +1,62 @@
+- file: 01_plain_use_case.rb
+  output: |
+    Hello, Ada
+- file: 02_composed_application.rb
+  output: |
+    Hello, Ada
+    Result is frozen: true
+- file: 03_order_domain.rb
+  output: |
+    confirmed
+    An order can only be confirmed once
+- file: 04_scoped_resources.rb
+  output: |
+    Same resource: true
+    opened, closed
+- file: 05_mapping.rb
+  output: |
+    UUID assigned: true
+    Same identity: true
+    Independent session: true
+    Stored state: pending
+- file: 06_associations.rb
+  output: |
+    Customer: Ada
+    Shared identity: true
+- file: 07_http.rb
+  output: |
+    HTTP 200
+    Order state: confirmed
+- file: 08_errors.rb
+  output: |
+    404 not_found
+    Occurrence ID present: true
+    409 order_not_confirmable
+    Occurrence ID present: true
+- file: 09_sqlite.rb
+  output: |
+    Schema version: 2
+    Read: pending
+    Write: confirmed
+    Unmapped note: gift
+    Open connections: 0
+- file: 10_grpc.rb
+  output: |
+    ready: confirmed
+- file: 11_ractor.rb
+  output: |
+    Total: 6
+    Request thread preserved: true
+- file: 12_box.rb
+  env:
+    RUBY_BOX: '1'
+  output: |
+    first application
+    second application
+    Definitions leaked: false
+- file: 13_testing.rb
+  output: |
+    PASS a zero price remains zero
+    PASS a price includes twenty percent tax
+    PASS negative prices are rejected
+    3 tests, 0 failures

data/examples/orders/application.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "object_framework"
+require_relative "domain"
+
+module OrdersExample
+  class Orders
+    def initialize(session:)
+      @session = session
+    end
+
+    def fetch(id)
+      @session.find(Order, id)
+    end
+  end
+
+  Bundle = Data.define(:application, :server, :storage)
+
+  def self.build(port: 0, storage: ObjectFramework::Memory::Storage.new)
+    mappings = ObjectFramework::Persistence::Mappings.new
+    mappings.define(Order, table: :orders) do
+      field :id
+      field :state
+      field :total_cents, type: :integer
+    end
+    app = ObjectFramework::Application.new(storage:, mappings:)
+    app.errors.register(OrderNotConfirmable, category: :conflict, code: "order_not_confirmable", title: "Order cannot be confirmed")
+    app.factory(:orders, dependencies: [:session]) { |session:| Orders.new(session:) }
+    app.operation(:confirm_order, use_case: ConfirmOrder, policy: :write, dependencies: [:orders])
+    parameters = ObjectFramework::HTTP::Parameters.new do
+      field :order_id, source: :path, key: :id, type: String
+    end
+    controller = ObjectFramework::HTTP::Controller.new(application: app, operation: :confirm_order, parameters:)
+    router = ObjectFramework::HTTP::Router.new
+    router.controller(:confirm_order, controller)
+    router.route("POST", "/orders/:id/confirm", controller: :confirm_order)
+    server = ObjectFramework::HTTP::Server.new(application: app, router:, port:)
+    app.install(server)
+    seed(storage)
+    Bundle.new(application: app, server:, storage:)
+  end
+
+  def self.seed(storage)
+    transaction = storage.begin_transaction(mode: :write)
+    transaction.insert(:orders, { id: "ready", state: "pending", total_cents: 1500 })
+    transaction.insert(:orders, { id: "rejected", state: "cancelled", total_cents: 500 })
+    transaction.commit
+  ensure
+    transaction&.close
+  end
+end

data/examples/orders/contracts.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+module OrdersExample
+  def self.grpc_contract
+    request = ObjectFramework::Protobuf::Message.new("ConfirmOrderRequest") do
+      field :order_id, 1, :string
+    end
+    confirmation = ObjectFramework::Protobuf::Message.new("OrderConfirmation") do
+      field :id, 1, :string
+      field :state, 2, :string
+      field :total_cents, 3, :int64
+    end
+    ObjectFramework::GRPC::Service.new("orders.Orders").tap do |service|
+      service.rpc(:ConfirmOrder, input: request, output: confirmation, controller: :confirm_order)
+    end
+  end
+end

data/examples/orders/domain.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module OrdersExample
+  class OrderNotConfirmable < StandardError; end
+
+  class Order
+    attr_accessor :id
+    attr_reader :state, :total_cents
+
+    def initialize(id: nil, state: "pending", total_cents:)
+      raise ArgumentError, "Total must be a nonnegative integer" unless total_cents.is_a?(Integer) && total_cents >= 0
+      raise ArgumentError, "Unknown order state" unless %w[pending confirmed cancelled].include?(state)
+      @id, @state, @total_cents = id, state, total_cents
+    end
+
+    def confirm
+      raise OrderNotConfirmable unless state == "pending" && total_cents.positive?
+      @state = "confirmed"
+    end
+  end
+
+  Confirmation = Data.define(:id, :state, :total_cents)
+
+  class ConfirmOrder
+    def initialize(orders:)
+      @orders = orders
+    end
+
+    def call(order_id:)
+      order = @orders.fetch(order_id)
+      order.confirm
+      Confirmation.new(id: order.id, state: order.state, total_cents: order.total_cents)
+    end
+  end
+end

data/examples/orders/export_proto.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "contracts"
+
+puts OrdersExample.grpc_contract.to_proto

data/examples/orders/grpc_client.py

@@ -0,0 +1,24 @@
+"""Confirm an order with grpcio and a contract exported by the Ruby server."""
+
+import importlib
+import pathlib
+import sys
+import tempfile
+
+import grpc
+from grpc_tools import protoc
+
+port, contract, order_id = int(sys.argv[1]), pathlib.Path(sys.argv[2]).resolve(), sys.argv[3]
+with tempfile.TemporaryDirectory() as directory:
+    if protoc.main(["protoc", f"-I{contract.parent}", f"--python_out={directory}", str(contract)]) != 0:
+        raise RuntimeError("Contract compilation failed")
+    sys.path.insert(0, directory)
+    messages = importlib.import_module(contract.stem + "_pb2")
+    with grpc.insecure_channel(f"127.0.0.1:{port}") as channel:
+        confirm = channel.unary_unary(
+            "/orders.Orders/ConfirmOrder",
+            request_serializer=messages.ConfirmOrderRequest.SerializeToString,
+            response_deserializer=messages.OrderConfirmation.FromString,
+        )
+        result = confirm(messages.ConfirmOrderRequest(order_id=order_id), timeout=3)
+        print(f"{result.id}: {result.state}")

data/examples/orders/grpc_server.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "application"
+require_relative "contracts"
+
+bundle = OrdersExample.build(port: Integer(ENV.fetch("HTTP_PORT", "8080")))
+controller = ObjectFramework::GRPC::Controller.new(application: bundle.application, operation: :confirm_order)
+grpc = ObjectFramework::GRPC::Server.new(application: bundle.application,
+  services: [OrdersExample.grpc_contract], controllers: { confirm_order: controller },
+  port: Integer(ENV.fetch("GRPC_PORT", "50051")))
+bundle.application.install(grpc)
+bundle.application.start
+puts "HTTP order API: http://127.0.0.1:#{bundle.server.port}"
+puts "gRPC order API: 127.0.0.1:#{grpc.port} (orders.Orders/ConfirmOrder)"
+
+signals = Queue.new
+%w[INT TERM].each { |signal| Signal.trap(signal) { signals << signal } }
+begin
+  signals.pop
+ensure
+  bundle.application.stop
+  bundle.storage.close
+end

data/examples/orders/server.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "application"
+
+bundle = OrdersExample.build(port: Integer(ENV.fetch("PORT", "8080")))
+bundle.application.start
+puts "Order confirmation API: http://127.0.0.1:#{bundle.server.port}"
+puts "POST /orders/ready/confirm; POST /orders/rejected/confirm"
+
+# Signal handlers only wake the main thread; resource cleanup stays in normal Ruby code.
+signals = Queue.new
+%w[INT TERM].each { |signal| Signal.trap(signal) { signals << signal } }
+begin
+  signals.pop
+ensure
+  bundle.application.stop
+  bundle.storage.close
+end

data/lib/object_framework/application.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  Factory = Data.define(:dependencies, :build, :close)
+  Operation = Data.define(:use_case, :policy, :dependencies)
+
+  class Application
+    attr_reader :errors, :reporter
+
+    def initialize(storage: nil, mappings: nil, errors: ErrorRegistry.new, reporter: nil)
+      @storage, @mappings, @errors = storage, mappings, errors
+      @reporter = reporter || FailureReporter.new(registry: errors)
+      @factories, @operations, @modules, @started_modules = {}, {}, {}, []
+      @started, @finalized = false, false
+    end
+
+    def factory(name, dependencies: [], close: false, &build)
+      mutable!
+      raise ConfigurationError, "Reserved execution dependency: #{name}" if %i[context session transaction].include?(name)
+      raise ConfigurationError, "Factory #{name} already registered" if @factories.key?(name)
+      raise ConfigurationError, "Factory requires a block" unless build
+      @factories[name] = Factory.new(dependencies: dependencies.dup.freeze, build:, close:)
+      self
+    end
+
+    def operation(name, use_case:, policy:, dependencies: [])
+      mutable!
+      raise ConfigurationError, "Operation #{name} already registered" if @operations.key?(name)
+      raise ConfigurationError, "Unknown transaction policy" unless %i[none read write].include?(policy)
+      @operations[name] = Operation.new(use_case:, policy:, dependencies: dependencies.dup.freeze)
+      self
+    end
+
+    def install(mod)
+      mutable!
+      raise ConfigurationError, "Module #{mod.name} already registered" if @modules.key?(mod.name)
+      @modules[mod.name] = mod
+      self
+    end
+
+    def start
+      raise ConfigurationError, "Application is already started" if @started
+      unless @finalized
+        modules = ordered_modules
+        modules.each { |mod| mod.configure(self) }
+        validate!
+        modules.each { |mod| mod.validate! if mod.respond_to?(:validate!) }
+        @factories.freeze
+        @operations.freeze
+        @modules.freeze
+        @errors.validate!
+        @finalized = true
+      end
+      ordered_modules.each do |mod|
+        mod.start
+        @started_modules << mod
+      end
+      @started = true
+      self
+    rescue Exception
+      stop
+      raise
+    end
+
+    def stop
+      error = nil
+      @started_modules.reverse_each do |mod|
+        mod.stop
+      rescue StandardError => failure
+        error ||= failure
+      end
+      @started_modules.clear
+      @started = false
+      raise error if error && !$!
+      self
+    end
+
+    def invoke(name, context: ExecutionContext.new, **arguments)
+      raise ConfigurationError, "Application is not started" unless @started
+      operation = @operations.fetch(name) { raise ConfigurationError, "Unknown operation: #{name}" }
+      Invocation.new(operation:, factories: @factories, storage: @storage, reporter: @reporter,
+                     mappings: @mappings).call(context:, **arguments)
+    end
+
+    def validate_operation!(name)
+      operation = @operations.fetch(name) { raise ConfigurationError, "Unknown operation: #{name}" }
+      unless operation.use_case.is_a?(Class) && operation.use_case.public_instance_methods.include?(:call)
+        raise ConfigurationError, "Use cases must be classes implementing call"
+      end
+      operation
+    end
+
+    private
+
+    def mutable!
+      raise ConfigurationError, "Application registrations are finalized" if @finalized
+    end
+
+    def validate!
+      @mappings&.validate!
+      @factories.each_key { |name| validate_dependency(name, []) }
+      @operations.each do |name, operation|
+        validate_operation!(name)
+        if operation.policy != :none && !@storage
+          raise ConfigurationError, "Transactional operations require storage"
+        end
+        operation.dependencies.each { |name| validate_dependency(name, [], policy: operation.policy) }
+      end
+    end
+
+    def validate_dependency(name, visiting, policy: nil)
+      return if name == :context
+      if %i[session transaction].include?(name)
+        raise ConfigurationError, "Storage dependency requires a transaction" if policy == :none
+        raise ConfigurationError, "Session requires mappings" if name == :session && !@mappings
+        return
+      end
+      raise ConfigurationError, "Dependency cycle: #{(visiting + [name]).join(' -> ')}" if visiting.include?(name)
+      factory = @factories.fetch(name) { raise ConfigurationError, "Unknown dependency: #{name}" }
+      factory.dependencies.each { |dependency| validate_dependency(dependency, visiting + [name], policy:) }
+    end
+
+    def ordered_modules
+      result = []
+      visit = lambda do |name, path|
+        raise ConfigurationError, "Module dependency cycle" if path.include?(name)
+        mod = @modules.fetch(name) { raise ConfigurationError, "Missing module: #{name}" }
+        return if result.include?(mod)
+        mod.requires.each { |dependency| visit.call(dependency, path + [name]) }
+        result << mod
+      end
+      @modules.each_key { |name| visit.call(name, []) }
+      result
+    end
+  end
+end

data/lib/object_framework/capabilities.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  module Capabilities
+    class Unsupported < ConfigurationError; end
+
+    class TaskFailure < StandardError
+      attr_reader :remote_class
+      def initialize(remote_class:, message:, backtrace:)
+        @remote_class = remote_class
+        super(message)
+        set_backtrace(backtrace)
+      end
+    end
+
+    def self.report
+      { ruby_box: Ruby::Box.enabled?, ractor: defined?(::Ractor) != nil,
+        yjit: RubyVM::YJIT.enabled?, zjit: RubyVM::ZJIT.enabled? }.freeze
+    end
+
+    class Definitions
+      def initialize
+        raise Unsupported, "Enable Ruby Box at process boot with RUBY_BOX=1" unless Ruby::Box.enabled?
+        @box = Ruby::Box.new
+      end
+
+      def load(path); @box.load(File.expand_path(path)); end
+      def require(path); @box.require(path); end
+      def evaluate(source); @box.eval(source); end
+      def constant(name); @box.const_get(name, false); end
+    end
+
+    class IsolatedTask
+      def initialize(task:)
+        raise ConfigurationError, "An isolated task must be a class or module implementing call" unless task.is_a?(Module) && task.respond_to?(:call)
+        @task = task
+      end
+
+      def call(input, context: nil)
+        context&.cancellation&.check!
+        payload = Values.detach(input)
+        # Only independent values cross this boundary; the request keeps its session.
+        ractor = Ractor.new(@task, payload) do |task, values|
+          begin
+            [:success, ObjectFramework::Values.detach(task.call(values))]
+          rescue StandardError => error
+            [:failure, error.class.name, error.message, error.backtrace]
+          end
+        end
+        outcome, *result = ractor.value
+        context&.cancellation&.check!
+        if outcome == :failure
+          raise TaskFailure.new(remote_class: result[0], message: result[1], backtrace: result[2])
+        end
+        Values.detach(result.first)
+      end
+    end
+  end
+end

data/lib/object_framework/errors.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ObjectFramework
+  class ConfigurationError < StandardError; end
+  class InvalidInput < StandardError; end
+  class NotFound < StandardError; end
+  class Conflict < StandardError; end
+  class Duplicate < StandardError; end
+  class Unavailable < StandardError; end
+  class CapacityExceeded < StandardError; end
+  class DeadlineExceeded < StandardError; end
+  class Cancelled < StandardError; end
+  class ClosedSession < StandardError; end
+  class UnsafeResult < StandardError; end
+
+  ErrorDescription = Data.define(:category, :code, :title, :details)
+
+  class ErrorRegistry
+    CATEGORIES = %i[bad_request invalid_input unauthenticated forbidden not_found conflict
+                    duplicate transaction_conflict rate_limited capacity unavailable
+                    deadline cancelled unimplemented internal].freeze
+    DEFAULTS = {
+      InvalidInput => [:invalid_input, "invalid_input", "Invalid input"],
+      NotFound => [:not_found, "not_found", "Resource not found"],
+      Conflict => [:transaction_conflict, "transaction_conflict", "Transaction conflict"],
+      Duplicate => [:duplicate, "duplicate", "Resource already exists"],
+      Unavailable => [:unavailable, "unavailable", "Storage unavailable"],
+      CapacityExceeded => [:capacity, "capacity_exceeded", "Capacity exhausted"],
+      DeadlineExceeded => [:deadline, "deadline_exceeded", "Deadline exceeded"],
+      Cancelled => [:cancelled, "cancelled", "Operation cancelled"]
+    }.freeze
+
+    def initialize
+      @registrations = {}
+      DEFAULTS.each { |type, (category, code, title)| register(type, category:, code:, title:) }
+    end
+
+    def register(type, category:, code:, title:, details: ->(_) { {} })
+      raise ConfigurationError, "Error registry is finalized" if @registrations.frozen?
+      raise ConfigurationError, "Expected an exception class" unless type.is_a?(Class) && type <= StandardError
+      raise ConfigurationError, "Duplicate error registration: #{type}" if @registrations.key?(type)
+      raise ConfigurationError, "Unknown error category: #{category}" unless CATEGORIES.include?(category)
+      raise ConfigurationError, "A stable code and title are required" if code.to_s.empty? || title.to_s.empty?
+      @registrations[type] = [category, code.to_s.dup.freeze, title.to_s.dup.freeze, details].freeze
+      self
+    end
+
+    def validate!
+      codes = @registrations.values.map { |registration| registration[1] }
+      raise ConfigurationError, "Ambiguous public error codes" unless codes.uniq.size == codes.size
+      @registrations.freeze
+      self
+    end
+
+    def resolve(exception)
+      type = exception.class.ancestors.find { |ancestor| @registrations.key?(ancestor) }
+      return ErrorDescription.new(category: :internal, code: "internal_error", title: "Internal server error", details: {}) unless type
+
+      category, code, title, details = @registrations.fetch(type)
+      ErrorDescription.new(category:, code:, title:, details: Values.detach(details.call(exception)))
+    end
+  end
+
+  class FailureReporter
+    def initialize(sink: ->(record) {}, registry: ErrorRegistry.new)
+      @sink, @registry = sink, registry
+    end
+
+    def report(exception, context:, secondary: false)
+      return if !secondary && !context.claim_failure
+
+      # Messages and argument values are deliberately absent: they can contain secrets.
+      record = {
+        operation_id: context.operation_id, code: @registry.resolve(exception).code,
+        exception: exception.class.name, cause: exception.cause&.class&.name,
+        backtrace: exception.backtrace&.dup, duration: context.elapsed,
+        transaction_state: context.transaction_state, secondary:
+      }
+      @sink.call(Values.detach(record))
+    rescue StandardError
+      # Diagnostics must never replace the exception being reported.
+      nil
+    end
+  end
+end