ruby-object-framework 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1e2d4ec32fc727f2bf3ace15ac7d7b258b4ebcbe8ec3b3e23402138c45225e6
-  data.tar.gz: e86edf614e5007fb417230d2fc590f5f1a3b356bea297301cba9154e7e31d9b5
+  metadata.gz: ce4bd20189a52219bc14f74365a6266ea8a86c6a4ff75a8893357c5405ec71ab
+  data.tar.gz: 5f3b4b8cc2d8acc3396a5bb3d82e859439ce6fe29f5fdb5f50499ca7d00ccfcf
 SHA512:
-  metadata.gz: b3afe27f57481683738558c93ad8c32b48b002eb26b271bec74efff482c4523a374a6aeeff0e0c12725ef569f408c9239629aad069a21efa10971269b2dd0262
-  data.tar.gz: a67817b8b87c0b5b0486deb700bce6670f8a2c43a70bb26a2e8122446c85d51884073827e3a4679fd45d54beb74ee33b223324a4d5168809bae425758fad5e25
+  metadata.gz: cfb86252c9efb72eaa78f6eb3718d9d63b4d5474857a4632236a59a77b6fcac069f7ce724c056a8f9d6b1ae594edf5fc06d0cdb85c4ea0d12c66e611d2eb7f43
+  data.tar.gz: 36649ffd4678ac362bc7b46b70285313909523ad9a670310d3fd332b4cba01b577c6b7e263746c8c8ce3ae5bd5253956b95276639c6b6250599c70687baaf992

data/API.md

@@ -8,9 +8,18 @@ the [ObjectFramework Guides](https://gstn-caruso.github.io/ruby-object-framework
 ## Application composition and execution
 
 Start with [Application](rdoc-ref:ObjectFramework::Application). Register
-invocation-scoped collaborators with `factory`, declare use cases with
-`operation`, and finalize the configuration with `start`. Always call `stop`
-in an `ensure` block.
+invocation-scoped collaborators with `bean` or `factory`, declare use cases
+with `operation`, and finalize the configuration with `start`. Always call
+`stop` in an `ensure` block.
+
+`bean(:name, SomeClass)` registers an ordinary Ruby class;
+`bean(:name) { |dependency:| ... }` registers a builder. Beans and operations
+infer dependencies from required constructor or block keywords when
+`dependencies:` is omitted. Optional keywords retain their defaults unless
+explicitly listed. Beans share the factory namespace and are constructed
+lazily once per invocation. Every subsequent invocation gets fresh instances.
+`close: true` closes a bean in reverse construction order on success or failure.
+`factory` keeps its explicit dependency list.
 
 Each operation declares `policy: :none`, `:read`, or `:write`. Transactional
 operations require storage. Dependencies are explicit constructor keywords;

data/README.md

@@ -7,6 +7,9 @@ invocation owns its resources and transaction.
 Read the [ObjectFramework Guides](https://gstn-caruso.github.io/ruby-object-framework/)
 for progressive tutorials, executable examples, and the reasoning behind the
 framework's design. Start with [Your first application](https://gstn-caruso.github.io/ruby-object-framework/getting_started.html).
+The [RDoc API reference](https://gstn-caruso.github.io/ruby-object-framework/api/index.html)
+documents classes, signatures, and execution contracts. You can also browse it
+inside the guides' [API reference section](https://gstn-caruso.github.io/ruby-object-framework/#api-reference).
 
 Development follows the six deliveries in [PLAN.md](PLAN.md). See the
 [implementation record](IMPLEMENTATION.md) for the current delivery status.
@@ -46,6 +49,8 @@ trusted-publisher registration and local packaging commands.
 
 Ruby **4.0.8** is required. Version files support asdf and other Ruby managers.
 The core and test runner use Ruby core and the standard library.
+The guide suite and documentation build additionally use the development-only
+RDoc dependency; run `bundle install` before running the full suite.
 
 ```sh
 ruby -Ilib:test test/run.rb
@@ -93,8 +98,8 @@ class Greet
 end
 
 app = ObjectFramework::Application.new
-app.factory(:greeting) { "Hello" }
-app.operation(:greet, use_case: Greet, policy: :none, dependencies: [:greeting])
+app.bean(:greeting) { "Hello" }
+app.operation(:greet, use_case: Greet, policy: :none)
 app.start
 begin
   app.invoke(:greet, name: "Ada") # => { message: "Hello, Ada" }
@@ -110,6 +115,19 @@ invocation, may declare their own dependencies, and may opt into cleanup with
 operation identifier and cooperative cancellation. Application registrations
 are finalized at startup. Separate application instances have separate registries.
 
+Register request-scoped beans with `app.bean(:name, SomeClass)` or
+`app.bean(:name) { |dependency:| ... }`. Beans and operations infer dependencies
+from required constructor or block keywords. Optional keywords keep their
+defaults; pass `dependencies: [...]` to inject them explicitly. Classes remain
+ordinary Ruby objects, and `factory` remains available for explicit wiring.
+
+Every invocation constructs only the beans it needs, reuses each named bean
+within that invocation, and discards them afterward. The next request gets fresh
+instances, including on the same keep-alive connection. Resource beans can use
+`close: true` for cleanup after success or failure. See the
+[composition guide](https://gstn-caruso.github.io/ruby-object-framework/composition_and_execution.html#register-request-scoped-beans)
+and run `ruby -Ilib examples/guides/14_request_beans.rb` for a complete example.
+
 Public results contain independent, immutable values: strings, numbers,
 booleans, symbols, nil, arrays, hashes, and `Data` objects composed of these.
 Returning an unsupported object or a cycle fails before commit. Managed domain
@@ -140,6 +158,10 @@ Keep public APIs, tests, documentation, and explanatory comments in English.
 Start a behavior change with a failing scenario in the dependency-free runner,
 then implement it and run the current delivery gate. Comments explaining
 protocol constraints and non-obvious decisions are welcome.
+Document public classes and methods with RDoc comments in `lib/`, and update
+the [API overview](API.md) when their contracts change. Build both the guides
+and API reference with `bundle exec ruby tools/build_guides.rb`; see the
+[documentation authoring instructions](docs/README.md) for preview and publishing.
 
 ## HTTP order example
 

data/THIRD_PARTY_NOTICES.md

@@ -12,6 +12,15 @@ the font files in `docs/assets/fonts/Inter-LICENSE.txt` and
 - IBM Plex: https://github.com/IBM/plex, revision
   `71f558992315a12ca1f06a2215d57962a1992162`.
 
+The static Inter regular, semibold, bold, and italic files were obtained from
+`https://rubyonrails.org/assets/fonts/Inter-*.woff2?v=4.0`, the same URLs used
+by Rails Guides, on October 23, 2026. They retain the Inter license above.
+IBM Plex Mono Text uses the exact file served at
+`https://rubyonrails.org/assets/fonts/IBMPlexMono-Text.woff2`, obtained on
+October 23, 2026, under the IBM Plex license above.
+Calibre is loaded from the Rails-hosted font URLs declared in
+`docs/assets/fonts.css`; Calibre font files are not distributed in this repository.
+
 The documentation stylesheet is an original implementation of the visual
 reference requested by the project: https://guides.rubyonrails.org/index.html.
 

data/examples/guides/14_request_beans.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+class RequestCounter
+  attr_reader :operation_id
+
+  def initialize(context:)
+    @operation_id, @count = context.operation_id, 0
+  end
+
+  def next_value
+    @count += 1
+  end
+
+  def close
+    puts "Counter closed"
+  end
+end
+
+class CountTwice
+  def initialize(first:, second:)
+    @first, @second = first, second
+  end
+
+  def call
+    { counts: [@first.next_value, @second.next_value], operation_id: @first.operation_id }
+  end
+end
+
+app = ObjectFramework::Application.new
+app.bean(:counter, RequestCounter, close: true)
+app.bean(:first) { |counter:| counter }
+app.bean(:second) { |counter:| counter }
+app.operation(:count, use_case: CountTwice, policy: :none)
+app.start
+begin
+  results = 2.times.map do |index|
+    result = app.invoke(:count)
+    puts "Request #{index + 1}: #{result[:counts].join(', ')}"
+    result
+  end
+  puts "Independent contexts: #{results[0][:operation_id] != results[1][:operation_id]}"
+ensure
+  app.stop
+end

data/examples/guides/manifest.yml

@@ -60,3 +60,10 @@
     PASS a price includes twenty percent tax
     PASS negative prices are rejected
     3 tests, 0 failures
+- file: 14_request_beans.rb
+  output: |
+    Counter closed
+    Request 1: 1, 2
+    Counter closed
+    Request 2: 1, 2
+    Independent contexts: true

data/lib/object_framework/application.rb

@@ -4,9 +4,23 @@ module ObjectFramework
   Factory = Data.define(:dependencies, :build, :close)
   Operation = Data.define(:use_case, :policy, :dependencies)
 
+  # Composes use cases, scoped collaborators, and lifecycle modules.
+  # Registrations belong to this instance and become immutable at #start.
+  #
+  #   app = ObjectFramework::Application.new
+  #   app.factory(:greeting) { "Hello" }
+  #   app.operation(:greet, use_case: Greet, policy: :none, dependencies: [:greeting])
+  #   app.start
+  #   begin
+  #     app.invoke(:greet, name: "Ada")
+  #   ensure
+  #     app.stop
+  #   end
   class Application
     attr_reader :errors, :reporter
 
+    # Creates an independent composition root. Transactional operations need
+    # +storage+; the reserved +session+ dependency also needs +mappings+.
     def initialize(storage: nil, mappings: nil, errors: ErrorRegistry.new, reporter: nil)
       @storage, @mappings, @errors = storage, mappings, errors
       @reporter = reporter || FailureReporter.new(registry: errors)
@@ -14,6 +28,11 @@ module ObjectFramework
       @started, @finalized = false, false
     end
 
+    # Registers an invocation-scoped collaborator, constructed lazily once per
+    # invocation. The block receives its declared dependencies as keywords.
+    # With <tt>close: true</tt>, cleanup calls the collaborator's +close+ in
+    # reverse construction order, including when the operation fails.
+    # +context+, +session+, and +transaction+ are reserved names. Returns +self+.
     def factory(name, dependencies: [], close: false, &build)
       mutable!
       raise ConfigurationError, "Reserved execution dependency: #{name}" if %i[context session transaction].include?(name)
@@ -23,14 +42,40 @@ module ObjectFramework
       self
     end
 
-    def operation(name, use_case:, policy:, dependencies: [])
+    # Registers an invocation-scoped bean from a Ruby class or a block.
+    # Required constructor/block keywords name its dependencies unless an
+    # explicit +dependencies+ list is supplied. Optional keywords keep their
+    # defaults. Beans are lazy, shared only within one invocation, and released
+    # with that invocation when <tt>close: true</tt>. Returns +self+.
+    #
+    #   app.bean(:orders, Orders)
+    #   app.bean(:client, close: true) { |context:| Client.new(context:) }
+    def bean(name, type = nil, dependencies: nil, close: false, &build)
+      raise ConfigurationError, "A bean accepts either a class or a block" if type && build
+      unless type.is_a?(Class) || (type.nil? && build)
+        raise ConfigurationError, "A bean requires a class or a block"
+      end
+      dependencies ||= keyword_dependencies(type ? type.instance_method(:initialize) : build)
+      build ||= ->(**arguments) { type.new(**arguments) }
+      factory(name, dependencies:, close:, &build)
+    end
+
+    # Registers a class implementing +call+. Dependencies become constructor
+    # keywords; omitting +dependencies+ infers required constructor keywords.
+    # #invoke arguments become +call+ keywords. +policy+ must be +:none+,
+    # +:read+, or +:write+. Returns +self+.
+    def operation(name, use_case:, policy:, dependencies: nil)
       mutable!
       raise ConfigurationError, "Operation #{name} already registered" if @operations.key?(name)
       raise ConfigurationError, "Unknown transaction policy" unless %i[none read write].include?(policy)
+      dependencies ||= use_case.is_a?(Class) ? keyword_dependencies(use_case.instance_method(:initialize)) : []
       @operations[name] = Operation.new(use_case:, policy:, dependencies: dependencies.dup.freeze)
       self
     end
 
+    # Registers a lifecycle module implementing +name+, +requires+, +configure+,
+    # +start+, and +stop+, and optionally +validate!+. Modules start in dependency
+    # order and stop in reverse order. Returns +self+.
     def install(mod)
       mutable!
       raise ConfigurationError, "Module #{mod.name} already registered" if @modules.key?(mod.name)
@@ -38,6 +83,9 @@ module ObjectFramework
       self
     end
 
+    # Configures modules, validates dependencies and policies, freezes
+    # registrations, and starts modules. Raises ConfigurationError for invalid
+    # composition. If startup fails, already-started modules are stopped.
     def start
       raise ConfigurationError, "Application is already started" if @started
       unless @finalized
@@ -62,6 +110,8 @@ module ObjectFramework
       raise
     end
 
+    # Stops started modules in reverse order, attempting every stop even if one
+    # fails. Preserves an exception already unwinding the caller. Returns +self+.
     def stop
       error = nil
       @started_modules.reverse_each do |mod|
@@ -75,6 +125,11 @@ module ObjectFramework
       self
     end
 
+    # Executes a registered use case in a fresh resource and transaction scope.
+    # Returns an independent, frozen value graph before resources are closed.
+    # Unsupported results raise UnsafeResult before flush or commit. Failures
+    # are reported and re-raised; failed commits are never automatically retried.
+    # The application must be started. +context+ defaults to a fresh context.
     def invoke(name, context: ExecutionContext.new, **arguments)
       raise ConfigurationError, "Application is not started" unless @started
       operation = @operations.fetch(name) { raise ConfigurationError, "Unknown operation: #{name}" }
@@ -92,6 +147,14 @@ module ObjectFramework
 
     private
 
+    def keyword_dependencies(callable)
+      parameters = callable.parameters
+      if parameters.any? { |kind, _| kind == :req }
+        raise ConfigurationError, "Automatic injection requires keyword arguments; wrap positional constructors in a bean block"
+      end
+      parameters.filter_map { |kind, name| name if kind == :keyreq }
+    end
+
     def mutable!
       raise ConfigurationError, "Application registrations are finalized" if @finalized
     end

data/lib/object_framework/capabilities.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # Optional Ruby Box, Ractor, and JIT capability reporting. The core application
+  # lifecycle does not require these experimental or VM-specific features.
   module Capabilities
     class Unsupported < ConfigurationError; end
 
@@ -13,11 +15,16 @@ module ObjectFramework
       end
     end
 
+    # Returns the current availability/enabled state of Ruby Box, Ractor,
+    # YJIT, and ZJIT. JIT comparisons run in separate benchmark processes.
     def self.report
       { ruby_box: Ruby::Box.enabled?, ractor: defined?(::Ractor) != nil,
         yjit: RubyVM::YJIT.enabled?, zjit: RubyVM::ZJIT.enabled? }.freeze
     end
 
+    # Owns application definitions in a separate Ruby Box.
+    # Requires Ruby to start with RUBY_BOX=1; enabling it later has no effect.
+    # Raises Unsupported when Ruby Box is disabled.
     class Definitions
       def initialize
         raise Unsupported, "Enable Ruby Box at process boot with RUBY_BOX=1" unless Ruby::Box.enabled?
@@ -30,12 +37,18 @@ module ObjectFramework
       def constant(name); @box.const_get(name, false); end
     end
 
+    # Runs a class/module's +self.call(input)+ in a new Ractor over independent
+    # values. Sessions and execution contexts stay on the owning request thread.
     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
 
+      # Returns a detached task result. Checks optional context cancellation
+      # before and after the computation; cannot interrupt a running Ractor.
+      # Remote StandardError failures become TaskFailure with the remote class
+      # name and backtrace. Use bounded computations.
       def call(input, context: nil)
         context&.cancellation&.check!
         payload = Values.detach(input)

data/lib/object_framework/errors.rb

@@ -15,6 +15,8 @@ module ObjectFramework
 
   ErrorDescription = Data.define(:category, :code, :title, :details)
 
+  # Maps exception classes to safe, transport-independent public descriptions.
+  # Configure it before Application#start finalizes registrations.
   class ErrorRegistry
     CATEGORIES = %i[bad_request invalid_input unauthenticated forbidden not_found conflict
                     duplicate transaction_conflict rate_limited capacity unavailable
@@ -35,6 +37,10 @@ module ObjectFramework
       DEFAULTS.each { |type, (category, code, title)| register(type, category:, code:, title:) }
     end
 
+    # Registers a StandardError subclass with a stable +code+ and +title+.
+    # +category+ must belong to CATEGORIES. The optional +details+ callable must
+    # return only explicitly safe public values. Duplicate types are rejected.
+    # Returns +self+.
     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
@@ -52,6 +58,8 @@ module ObjectFramework
       self
     end
 
+    # Returns an ErrorDescription for the closest registered ancestor.
+    # Unregistered exceptions receive a generic internal-error description.
     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
@@ -61,11 +69,17 @@ module ObjectFramework
     end
   end
 
+  # Reports one primary failure per ExecutionContext and secondary cleanup
+  # failures. Records exclude exception messages and input values.
   class FailureReporter
+    # +sink+ receives immutable diagnostic hashes. Sink failures are suppressed
+    # so diagnostics cannot replace the original application failure.
     def initialize(sink: ->(record) {}, registry: ErrorRegistry.new)
       @sink, @registry = sink, registry
     end
 
+    # Sends operation ID, public code, exception/cause class names, backtrace,
+    # elapsed duration, transaction outcome, and the +secondary+ flag to the sink.
     def report(exception, context:, secondary: false)
       return if !secondary && !context.claim_failure
 

data/lib/object_framework/execution.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # Copies storage state and detaches values crossing an invocation boundary.
   module Values
     # Storage values are immutable; domain state receives its own editable copy.
     def self.mutable_copy(value)
@@ -13,6 +14,8 @@ module ObjectFramework
       end
     end
 
+    # Returns an independent, immutable graph of supported scalar, Array, Hash,
+    # and Data values. Raises UnsafeResult for cycles and unsupported objects.
     def self.detach(value, visiting = {})
       composite = value.is_a?(Array) || value.is_a?(Hash) || value.is_a?(Data)
       if composite
@@ -32,11 +35,15 @@ module ObjectFramework
     end
   end
 
+  # Thread-safe cooperative cancellation and a monotonic-clock deadline.
+  # Work must call #check! at suitable boundaries to observe either condition.
   class Cancellation
+    # +deadline+ is an absolute monotonic timestamp, or +nil+ for no deadline.
     def initialize(deadline: nil, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @deadline, @clock, @mutex, @cancelled = deadline, clock, Mutex.new, false
     end
 
+    # Requests cancellation without interrupting or terminating the worker.
     def cancel
       @mutex.synchronize { @cancelled = true }
     end
@@ -49,6 +56,8 @@ module ObjectFramework
       @mutex.synchronize { @deadline = deadline }
     end
 
+    # Raises Cancelled if cancellation was requested, or DeadlineExceeded if
+    # the monotonic deadline has passed.
     def check!
       raise Cancelled, "Operation cancelled" if @mutex.synchronize { @cancelled }
       limit = deadline
@@ -56,10 +65,14 @@ module ObjectFramework
     end
   end
 
+  # Invocation metadata shared by execution, transport, and diagnostics.
+  # Inject it through the reserved +context+ dependency; do not share sessions
+  # or this context with isolated tasks.
   class ExecutionContext
     attr_reader :operation_id, :cancellation
     attr_accessor :transaction_state
 
+    # Generates an operation UUID and records a monotonic start time.
     def initialize(cancellation: Cancellation.new)
       @operation_id = SecureRandom.uuid.freeze
       @cancellation, @started_at = cancellation, monotonic
@@ -67,6 +80,7 @@ module ObjectFramework
       @mutex = Mutex.new
     end
 
+    # Returns the elapsed time in seconds since construction.
     def elapsed
       monotonic - @started_at
     end
@@ -85,6 +99,7 @@ module ObjectFramework
     end
   end
 
+  # Resolves and closes the collaborators belonging to one invocation.
   class Scope
     def initialize(factories, context:)
       @factories, @context, @instances, @resources = factories, context, { context: }, []
@@ -114,6 +129,8 @@ module ObjectFramework
     end
   end
 
+  # Executes a use case, detaches its result, and owns transaction cleanup.
+  # Applications normally enter this lifecycle through Application#invoke.
   class Invocation
     def initialize(operation:, factories:, storage:, reporter:, mappings: nil)
       @operation, @factories, @storage, @reporter, @mappings = operation, factories, storage, reporter, mappings

data/lib/object_framework/grpc/server.rb

@@ -66,9 +66,18 @@ module ObjectFramework
       end
     end
 
+    # Application lifecycle module serving unary and streaming gRPC calls.
+    # Every admitted RPC receives a new thread and an ExecutionContext.
+    # Controllers own the choice of operation boundaries within a stream.
+    # Install through Application#install before starting the application.
     class Server
       attr_reader :name, :port
 
+      # +services+ contains Service descriptors; +controllers+ maps their keys
+      # to callable controllers. Limits bound requests, connections, message
+      # bytes, and header bytes. Timeouts are in seconds; cancellation is
+      # cooperative. Optional +tls_context+ must supply a certificate and key;
+      # startup configures HTTP/2 ALPN. Compression supports identity only.
       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,

data/lib/object_framework/grpc/service.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # Native gRPC services and streaming over the framework's HTTP/2 transport.
   module GRPC
     Method = Data.define(:name, :input, :output, :controller, :client_streaming, :server_streaming)
 
+    # Declares a gRPC service using Protobuf::Message contracts.
+    # Descriptors export proto3 source without generated Ruby message classes.
     class Service
       attr_reader :name, :methods
 
+      # +name+ is a qualified service name, for example +orders.Orders+.
       def initialize(name)
         parts = name.to_s.split(".", -1)
         raise ConfigurationError, "Invalid service name" if parts.empty?
@@ -14,6 +18,9 @@ module ObjectFramework
         @name, @methods = name.to_s.dup.freeze, {}
       end
 
+      # Adds an RPC with input/output message descriptors and a controller key.
+      # Both streaming flags default to false (unary); enable one for client
+      # or server streaming, or both for bidirectional streaming. Returns +self+.
       def rpc(name, input:, output:, controller:, client_streaming: false, server_streaming: false)
         raise ConfigurationError, "Service is finalized" if @methods.frozen?
         name = Protobuf.name(name)
@@ -29,6 +36,8 @@ module ObjectFramework
         freeze
       end
 
+      # Returns a complete proto3 contract with dependent messages and enums.
+      # Raises ConfigurationError if distinct descriptors reuse a type name.
       def to_proto
         definitions = {}
         visit = lambda do |type|

data/lib/object_framework/http/presentation.rb

@@ -4,6 +4,8 @@ module ObjectFramework
   module HTTP
     Response = Data.define(:status, :headers, :body)
 
+    # Converts independent result values into a JSON Response with status 200.
+    # Data objects are represented as JSON objects.
     class JSONPresenter
       def call(value)
         Response.new(status: 200, headers: { "Content-Type" => "application/json" }, body: JSON.generate(json_value(value)))
@@ -21,6 +23,8 @@ module ObjectFramework
       end
     end
 
+    # Presents registered safe errors as RFC 9457 problem details, including
+    # the ExecutionContext operation ID. Exception messages are not exposed.
     class ProblemPresenter
       STATUSES = {
         bad_request: 400, invalid_input: 422, unauthenticated: 401, forbidden: 403,

data/lib/object_framework/http/router.rb

@@ -1,15 +1,23 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # HTTP/1.1 routing, presentation, and bounded request serving.
   module HTTP
     Route = Data.define(:method, :pattern, :controller, :expression, :names)
     Match = Data.define(:controller, :params, :allow)
 
+    # Maps method/path patterns to explicit controller instances.
+    # Configuration is finalized by the server at application startup.
+    #
+    #   router.controller(:confirm, controller)
+    #   router.route(:post, "/orders/:id/confirm", controller: :confirm)
     class Router
       def initialize
         @controllers, @routes = {}, []
       end
 
+      # Registers a controller implementing +call(request, context:)+.
+      # Controllers normalize transport inputs and invoke application operations.
       def controller(name, instance)
         mutable!
         raise ConfigurationError, "Duplicate controller: #{name}" if @controllers.key?(name)
@@ -17,6 +25,8 @@ module ObjectFramework
         self
       end
 
+      # Adds a method and path pattern with optional +:parameter+ segments.
+      # Static routes take precedence over parameterized routes. Returns +self+.
       def route(method, pattern, controller:)
         mutable!
         method = method.to_s.upcase
@@ -49,6 +59,9 @@ module ObjectFramework
         self
       end
 
+      # Returns a Match with controller, decoded path parameters, and allowed
+      # methods. Supports HEAD through GET and automatic OPTIONS. Raises
+      # NotFound, MethodNotAllowed, or BadRequest for invalid requests.
       def resolve(method, path)
         matching = path == "*" ? @routes : @routes.select { |route| route.expression.match?(path) }
         raise NotFound, "Route not found" if matching.empty?

data/lib/object_framework/http/server.rb

@@ -13,9 +13,17 @@ module ObjectFramework
       end
     end
 
+    # Application lifecycle module serving HTTP/1.1 on a dispatcher and one new
+    # thread per admitted request. Keep-alive requests execute sequentially.
+    # Install with Application#install before startup; the application owns
+    # listener startup, cooperative shutdown, and controller validation.
     class Server
       attr_reader :port, :name
 
+      # Configures admission limits and timeouts in seconds. +port+ zero lets
+      # the OS assign a port, available through #port after startup.
+      # +tls_context+ is an optional OpenSSL context with application-provided
+      # certificate and private key. Execution cancellation is cooperative.
       def initialize(application:, router:, host: "127.0.0.1", port: 0, name: :http,
                      parser: Parser.new, presenter: JSONPresenter.new, problem_presenter: nil,
                      max_requests: 128, max_connections: 1024, header_timeout: 10,

data/lib/object_framework/memory/storage.rb

@@ -1,12 +1,19 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # Volatile, process-local persistence using revision-checked snapshots.
   module Memory
+    # Thread-safe storage adapter. Writes publish their complete snapshot
+    # atomically; a competing commit raises Conflict without automatic retry.
+    # Data is lost when the storage is closed or the process exits.
     class Storage
       def initialize
         @mutex, @tables, @revision, @closed = Mutex.new, {}, 0, false
       end
 
+      # Opens an independent snapshot in +:read+ or +:write+ mode.
+      # The caller must close the transaction; Application#invoke owns this
+      # lifecycle when the adapter is installed in an application.
       def begin_transaction(mode:)
         @mutex.synchronize do
           raise Unavailable, "Storage is closed" if @closed

data/lib/object_framework/persistence/mapping.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # External domain mappings, immutable queries, and invocation-owned sessions.
   module Persistence
+    # Converts a field between domain values and independent storage values.
     class Converter
       def initialize(dump: ->(value) { value }, load: ->(value) { value })
         @dump, @load = dump, load
@@ -15,7 +17,32 @@ module ObjectFramework
     Field = Data.define(:name, :column, :type, :converter, :reader, :writer)
     Association = Data.define(:name, :kind, :target, :foreign_key, :reader, :writer)
 
+    # Explicit association declarations used by Mapping.
     module AssociationDSL
+      ##
+      # :method: belongs_to
+      # :args: name, target:, foreign_key:, read: nil, write: nil
+      #
+      # Declares a reference to +target+, storing its UUID in +foreign_key+ on
+      # this mapping's table. The target must have a registered Mapping.
+      # Optional +read+ and +write+ callables replace public attribute accessors.
+      # Returns +self+. Associations load only when requested through a
+      # Session#find or Session#query load plan.
+      #
+      #   belongs_to :customer, target: Customer, foreign_key: :customer_id
+
+      ##
+      # :method: has_many
+      # :args: name, target:, foreign_key:, read: nil, write: nil
+      #
+      # Declares a collection of +target+ entities whose +foreign_key+ refers
+      # to this entity's UUID. The target mapping must expose that foreign key
+      # as a field or a belongs-to association. Optional +read+ and +write+
+      # callables replace public attribute accessors. Returns +self+.
+      # Collections load only through an explicit session load plan.
+      #
+      #   has_many :purchases, target: Purchase, foreign_key: :customer_id
+
       %i[belongs_to has_many].each do |kind|
         define_method(kind) do |name, target:, foreign_key:, read: nil, write: nil|
           mutable!
@@ -33,6 +60,9 @@ module ObjectFramework
       end
     end
 
+    # Describes how an ordinary Ruby class is hydrated and stored.
+    # An +id+ field mapped to the +id+ column is required. Declarations become
+    # immutable when their Mappings collection is validated at startup.
     class Mapping
       include AssociationDSL
       TYPES = %i[string integer float boolean blob].freeze
@@ -44,6 +74,9 @@ module ObjectFramework
         @builder = ->(attributes) { entity_class.new(**attributes) }
       end
 
+      # Maps an attribute to a column using a type in TYPES. Optional +read+
+      # and +write+ callables replace public attribute accessors. +converter+
+      # supplies +dump+ and +load+ transformations. Returns +self+.
       def field(name, column: name, type: :string, converter: Converter.new, read: nil, write: nil)
         mutable!
         name, column = Query.identifier(name), Query.identifier(column)
@@ -55,6 +88,8 @@ module ObjectFramework
         self
       end
 
+      # Replaces keyword construction with a callable receiving an attributes
+      # hash. Use this when hydration needs a domain-specific constructor.
       def build(&builder)
         mutable!
         @builder = builder
@@ -107,6 +142,13 @@ module ObjectFramework
       end
     end
 
+    # Owns the application's mappings without modifying domain classes.
+    #
+    #   mappings = ObjectFramework::Persistence::Mappings.new
+    #   mappings.define(Order, table: :orders) do
+    #     field :id
+    #     field :status
+    #   end
     class Mappings
       include Enumerable
 
@@ -114,6 +156,8 @@ module ObjectFramework
         @mappings = {}
       end
 
+      # Registers one Mapping per domain class and table. Evaluates the
+      # declaration block against that mapping and returns it.
       def define(entity_class, table:, &description)
         raise ConfigurationError, "Mappings are finalized" if @mappings.frozen?
         raise ConfigurationError, "Duplicate entity mapping" if @mappings.key?(entity_class)

data/lib/object_framework/persistence/query.rb

@@ -4,6 +4,10 @@ module ObjectFramework
   module Persistence
     Criterion = Data.define(:field, :operator, :value)
 
+    # Immutable query shared by storage adapters. Filters and ordering produce
+    # new queries; rows use +id+ as a deterministic final ordering key.
+    #
+    #   Query.new.where(status: "ready").order(:id).limit(20).offset(40)
     class Query
       OPERATORS = %i[eq ne gt gte lt lte in].freeze
       attr_reader :table, :criteria, :ordering, :row_limit, :row_offset
@@ -24,10 +28,13 @@ module ObjectFramework
         copy(table:)
       end
 
+      # Adds equality criteria for every supplied field. Returns a new query.
       def where(**attributes)
         attributes.reduce(self) { |query, (field, value)| query.compare(field, :eq, value) }
       end
 
+      # Adds +:eq+, +:ne+, +:gt+, +:gte+, +:lt+, +:lte+, or +:in+.
+      # +:in+ requires an Array. Values are detached on construction.
       def compare(field, operator, value)
         raise ConfigurationError, "Unsupported query operator" unless OPERATORS.include?(operator)
         raise ConfigurationError, "IN requires an array" if operator == :in && !value.is_a?(Array)
@@ -35,15 +42,18 @@ module ObjectFramework
         copy(criteria: criteria + [criterion])
       end
 
+      # Appends an ascending or descending ordering using +:asc+ or +:desc+.
       def order(field, direction = :asc)
         raise ConfigurationError, "Invalid ordering direction" unless %i[asc desc].include?(direction)
         copy(ordering: ordering + [[self.class.identifier(field), direction].freeze])
       end
 
+      # Returns a query limited to a nonnegative integer number of rows.
       def limit(count)
         copy(row_limit: nonnegative(count))
       end
 
+      # Returns a query skipping a nonnegative integer number of rows.
       def offset(count)
         copy(row_offset: nonnegative(count))
       end

data/lib/object_framework/persistence/session.rb

@@ -65,6 +65,9 @@ module ObjectFramework
       def clear; @entries.clear; end
     end
 
+    # Owns an identity map and unit of work for one active transaction.
+    # Managed entities stay inside the invocation; return independent values
+    # to callers. Application#invoke flushes and closes its session automatically.
     class Session
       attr_reader :transaction
 
@@ -74,6 +77,9 @@ module ObjectFramework
         @closed, @removed = false, {}
       end
 
+      # Tracks a new mapped entity, assigning a UUID when its identity is nil.
+      # Returns the entity. Duplicate identities and previously removed
+      # entities cannot be registered as new objects in this session.
       def add(entity)
         active!
         mapping = @mappings.fetch(entity.class)
@@ -88,6 +94,9 @@ module ObjectFramework
         entity
       end
 
+      # Finds a mapped entity by identity or raises NotFound. Repeated lookups
+      # return the same object. +load+ explicitly selects associations, with
+      # nested hashes for nested loading; no implicit lazy loading occurs.
       def find(type, id, load: [])
         active!
         raise NotFound, "Entity was removed" if @removed.key?([type, id])
@@ -102,6 +111,8 @@ module ObjectFramework
         entity
       end
 
+      # Returns managed entities matching an immutable Query and optional
+      # association loading plan. Removed identities are excluded.
       def query(type, query = Query.new, load: [])
         active!
         mapping = @mappings.fetch(type)
@@ -112,6 +123,7 @@ module ObjectFramework
         end
       end
 
+      # Schedules deletion of a managed entity, or discards a pending insert.
       def remove(entity)
         active!
         id = @work.entry(entity).identity
@@ -120,6 +132,8 @@ module ObjectFramework
         @identities.remove(entity.class, id)
       end
 
+      # Writes tracked inserts, changes, and deletions without committing.
+      # Managed identities cannot change. Requires an active session.
       def flush
         active!
         @work.flush

data/lib/object_framework/persistence/transaction.rb

@@ -5,6 +5,9 @@ module ObjectFramework
     class ClosedTransaction < StandardError; end
     class ReadOnlyTransaction < StandardError; end
 
+    # Base lifecycle for read/write storage transactions. Adapters implement
+    # row access, commit, and storage cleanup. #close rolls back an active
+    # transaction and is safe to repeat. Committed transactions cannot be reused.
     class Transaction
       attr_reader :state, :mode
 

data/lib/object_framework/protobuf.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module ObjectFramework
+  # Ruby descriptors and wire encoding for proto3 messages and enums.
   module Protobuf
     SCALARS = {
       int32: 0, int64: 0, uint32: 0, uint64: 0, sint32: 0, sint64: 0, bool: 0,
@@ -59,6 +60,8 @@ module ObjectFramework
       end
     end
 
+    # Immutable proto3 enum declaration. Its first value must be zero, and
+    # names and numeric values must be unique and valid for proto3.
     class Enum
       attr_reader :name, :values
       def initialize(name, **values)
@@ -76,6 +79,14 @@ module ObjectFramework
 
     Field = Data.define(:name, :number, :type, :repeated, :packed)
 
+    # Immutable message descriptor encoding and decoding ordinary value hashes.
+    # Declare fields in the construction block.
+    #
+    #   message = ObjectFramework::Protobuf::Message.new("Greeting") do
+    #     field :text, 1, :string
+    #   end
+    #   bytes = message.encode(text: "Hello")
+    #   message.decode(bytes) # => { text: "Hello" }
     class Message
       attr_reader :name, :fields
 
@@ -87,6 +98,9 @@ module ObjectFramework
         freeze
       end
 
+      # Declares a unique field name and proto3 number. +type+ is a scalar in
+      # SCALARS, another Message, or an Enum. Repeated numeric fields use packed
+      # encoding by default. Declare fields only during construction.
       def field(name, number, type, repeated: false, packed: true)
         name = Protobuf.name(name).to_sym
         unless number.is_a?(Integer) && number.between?(1, 2**29 - 1) && !number.between?(19_000, 19_999)
@@ -97,6 +111,9 @@ module ObjectFramework
         @fields << Field.new(name:, number:, type:, repeated:, packed:)
       end
 
+      # Encodes a Hash or Data value, or keyword attributes, as binary proto3.
+      # Raises InvalidInput for unknown fields, invalid values, or excessive
+      # nesting. Repeated fields require arrays.
       def encode(values = nil, depth: 0, **attributes)
         raise InvalidInput, "Protobuf nesting limit exceeded" if depth >= 64
         raise InvalidInput, "Pass message values once" if values && !attributes.empty?
@@ -122,6 +139,8 @@ module ObjectFramework
         end
       end
 
+      # Decodes binary proto3 into a Hash, supplying defaults for absent fields
+      # and skipping unknown fields. Malformed input raises InvalidInput.
       def decode(bytes, depth: 0, initial: nil)
         raise InvalidInput, "Protobuf nesting limit exceeded" if depth >= 64
         cursor = Wire::Cursor.new(bytes)

data/lib/object_framework/sqlite/schema.rb

@@ -5,10 +5,15 @@ module ObjectFramework
     ForeignKey = Data.define(:table, :column, :target)
     Migration = Data.define(:version, :actions)
 
+    # Declared SQLite tables, foreign keys, and consecutive schema migrations.
+    # Version 1 creates the initial tables. Storage finalizes this declaration
+    # and applies pending migrations transactionally during construction.
     class Schema
       TYPES = { string: "TEXT", integer: "INTEGER", float: "REAL", boolean: "INTEGER", blob: "BLOB" }.freeze
       attr_reader :tables, :foreign_keys, :migrations
 
+      # Validates domain mappings and derives tables and belongs-to foreign
+      # keys. Returns a schema that can still receive migration declarations.
       def self.from_mappings(mappings)
         mappings.validate!
         keys = mappings.flat_map do |mapping|
@@ -30,6 +35,10 @@ module ObjectFramework
         @migrations = [Migration.new(version: 1, actions: [].freeze)]
       end
 
+      # Declares the next consecutive version using Editor#add_column.
+      # Declare migrations before constructing Storage. Returns +self+.
+      #
+      #   schema.migration(2) { add_column :orders, :note, type: :string }
       def migration(version, &declaration)
         raise ConfigurationError, "Schema is finalized" if frozen?
         raise ConfigurationError, "Migration versions must be consecutive" unless version == @migrations.last.version + 1

data/lib/object_framework/sqlite/storage.rb

@@ -21,9 +21,16 @@ module ObjectFramework
       end
     end
 
+    # Optional file-backed SQLite adapter, requiring the sqlite3 gem.
+    # Each transaction owns a connection with foreign keys enabled and FULL
+    # synchronization. Uses DELETE journaling, IMMEDIATE writes, and DEFERRED
+    # reads. Commit failures are propagated without automatic retry.
     class Storage
       attr_reader :schema_version
 
+      # Finalizes +schema+ and migrates the database at +path+. In-memory paths
+      # are rejected. +lock_timeout+ bounds lock waiting in seconds; execution
+      # cancellation and deadlines may interrupt that wait earlier.
       def initialize(path:, schema:, lock_timeout: 1)
         raise ConfigurationError, "SQLite requires a database file path" if path.to_s.empty? || path.to_s == ":memory:"
         raise ConfigurationError, "Lock timeout must be positive" unless lock_timeout.is_a?(Numeric) && lock_timeout.positive?
@@ -52,6 +59,8 @@ module ObjectFramework
         raise
       end
 
+      # Rejects new transactions. Already-open transactions retain ownership
+      # of their connections until they close. Stop applications first.
       def close
         @mutex.synchronize { @closed = true }
       end

data/lib/object_framework/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ObjectFramework
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/object_framework.rb

@@ -25,6 +25,11 @@ require_relative "object_framework/grpc/messages"
 require_relative "object_framework/http2/connection"
 require_relative "object_framework/grpc/server"
 
+# Applications composed from ordinary Ruby objects, with explicit dependencies,
+# invocation-scoped resources, and transport-independent use cases.
+#
+# Application is the composition root. Persistence, HTTP, GRPC, and Protobuf
+# supply adapters and contracts; SQLite and Capabilities load on demand.
 module ObjectFramework
   autoload :SQLite, File.expand_path("object_framework/sqlite", __dir__)
   autoload :Capabilities, File.expand_path("object_framework/capabilities", __dir__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-object-framework
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Gastón Caruso
@@ -35,6 +35,7 @@ files:
 - examples/guides/11_ractor.rb
 - examples/guides/12_box.rb
 - examples/guides/13_testing.rb
+- examples/guides/14_request_beans.rb
 - examples/guides/manifest.yml
 - examples/orders/application.rb
 - examples/orders/contracts.rb