ruby-object-framework 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1e2d4ec32fc727f2bf3ace15ac7d7b258b4ebcbe8ec3b3e23402138c45225e6
+  data.tar.gz: e86edf614e5007fb417230d2fc590f5f1a3b356bea297301cba9154e7e31d9b5
+SHA512:
+  metadata.gz: b3afe27f57481683738558c93ad8c32b48b002eb26b271bec74efff482c4523a374a6aeeff0e0c12725ef569f408c9239629aad069a21efa10971269b2dd0262
+  data.tar.gz: a67817b8b87c0b5b0486deb700bce6670f8a2c43a70bb26a2e8122446c85d51884073827e3a4679fd45d54beb74ee33b223324a4d5168809bae425758fad5e25

data/API.md

@@ -0,0 +1,78 @@
+# ObjectFramework API
+
+This reference is generated from the Ruby source in `lib/`. It describes the
+objects you compose, their method signatures, and the contracts callers must
+honor. For a progressive introduction and complete runnable applications, read
+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.
+
+Each operation declares `policy: :none`, `:read`, or `:write`. Transactional
+operations require storage. Dependencies are explicit constructor keywords;
+`context`, `session`, and `transaction` are reserved execution dependencies.
+The latter two require a transactional operation, and sessions require mappings.
+
+[ExecutionContext](rdoc-ref:ObjectFramework::ExecutionContext) carries a generated
+operation identifier and [Cancellation](rdoc-ref:ObjectFramework::Cancellation).
+Results must contain independent values: strings, numbers, booleans, symbols,
+nil, arrays, hashes, and `Data` objects composed of these. They are copied and
+frozen before flush and commit. Cycles and unsupported objects raise
+[UnsafeResult](rdoc-ref:ObjectFramework::UnsafeResult).
+
+## Persistence
+
+[Mappings](rdoc-ref:ObjectFramework::Persistence::Mappings) describes ordinary
+domain objects through [Mapping](rdoc-ref:ObjectFramework::Persistence::Mapping).
+Each mapping needs an `id` field stored in the `id` column. Associations load
+only when explicitly requested through a session's `load:` plan.
+
+[Session](rdoc-ref:ObjectFramework::Persistence::Session) owns identity and change
+tracking within an invocation. Use `add`, `find`, `query`, and `remove` inside
+the use case; return values instead of managed entities. The invocation flushes
+the session, commits, and closes its resources. A closed session cannot be reused.
+
+[Query](rdoc-ref:ObjectFramework::Persistence::Query) is immutable. Each filter,
+comparison, ordering, limit, or offset returns a new query. Queries run with
+[Memory::Storage](rdoc-ref:ObjectFramework::Memory::Storage) or the optional
+[SQLite::Storage](rdoc-ref:ObjectFramework::SQLite::Storage). SQLite requires the
+`sqlite3` gem; [SQLite::Schema](rdoc-ref:ObjectFramework::SQLite::Schema) derives
+tables from mappings and accepts consecutive migrations before storage startup.
+Commit failures are never automatically retried.
+
+## HTTP, protobuf, and gRPC
+
+[HTTP::Router](rdoc-ref:ObjectFramework::HTTP::Router) binds method/path patterns
+to explicit controllers. Install [HTTP::Server](rdoc-ref:ObjectFramework::HTTP::Server)
+in the application to serve HTTP/1.1 with bounded admission and request timeouts.
+[HTTP::JSONPresenter](rdoc-ref:ObjectFramework::HTTP::JSONPresenter) formats values;
+[HTTP::ProblemPresenter](rdoc-ref:ObjectFramework::HTTP::ProblemPresenter) formats
+safe error descriptions as problem details.
+
+[Protobuf::Message](rdoc-ref:ObjectFramework::Protobuf::Message) declares proto3
+fields and encodes or decodes ordinary hashes.
+[GRPC::Service](rdoc-ref:ObjectFramework::GRPC::Service) declares unary and
+streaming methods and exports their `.proto` contract. Install
+[GRPC::Server](rdoc-ref:ObjectFramework::GRPC::Server) with service descriptors
+and controllers. Streaming controllers invoke operations per message or batch,
+then yield independent values after their transactions finish.
+
+## Failures and optional capabilities
+
+Register domain exceptions in [ErrorRegistry](rdoc-ref:ObjectFramework::ErrorRegistry)
+before startup. The closest registered ancestor supplies the public category,
+code, title, and explicitly safe details. Unexpected exceptions receive a generic
+description. [FailureReporter](rdoc-ref:ObjectFramework::FailureReporter) sends
+immutable diagnostic records to a callable sink without exception messages or
+input values.
+
+[Capabilities::Definitions](rdoc-ref:ObjectFramework::Capabilities::Definitions)
+loads definitions into a Ruby Box when Ruby starts with `RUBY_BOX=1`.
+[Capabilities::IsolatedTask](rdoc-ref:ObjectFramework::Capabilities::IsolatedTask)
+runs bounded computations over independent values in a new Ractor. Cancellation
+checks happen before and after that computation; they do not forcibly terminate
+the Ractor. These capabilities are optional.

data/README.md

@@ -0,0 +1,250 @@
+# ObjectFramework
+
+A modular Ruby framework for applications built from collaborating objects.
+Use cases are ordinary Ruby classes, dependencies are explicit, and each
+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).
+
+Development follows the six deliveries in [PLAN.md](PLAN.md). See the
+[implementation record](IMPLEMENTATION.md) for the current delivery status.
+The initial implementation includes HTTP/1.1, native gRPC streaming, HashMap and
+SQLite persistence, and optional Ruby execution capabilities.
+
+## Installation
+
+Install the gem on Ruby 4.0.8:
+
+```sh
+gem install ruby-object-framework
+```
+
+Or add it to your application's Gemfile:
+
+```ruby
+gem "ruby-object-framework", require: "object_framework"
+```
+
+Load the framework with `require "object_framework"`. The gem includes all
+framework modules and runnable examples. SQLite remains optional; applications
+using that adapter must also declare `gem "sqlite3", "~> 2.10", ">= 2.10.1"`.
+
+## Automatic releases
+
+After verification succeeds on `main`, semantic-release updates the Ruby version
+and lockfile, creates a version tag, publishes to RubyGems.org, and attaches the
+gem and release notes to a GitHub release. Breaking changes increment major,
+`feat` increments minor, and other changes increment patch, including docs-only
+merges. The first automated release is `1.0.0`.
+
+See [release setup and recovery](docs/RELEASING.md) for the one-time RubyGems
+trusted-publisher registration and local packaging commands.
+
+## Requirements and tests
+
+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.
+
+```sh
+ruby -Ilib:test test/run.rb
+```
+
+For the full interoperability gate, prepare the independent Python clients:
+
+```sh
+bundle install
+python3 -m venv .venv
+.venv/bin/python -m pip install -r test/interop/requirements.txt
+ruby -Ilib:test test/run.rb
+```
+
+Python dependencies are test clients; the framework does not load them. Set
+`OBJECT_FRAMEWORK_INTEROP_PYTHON` to use an existing test environment.
+
+Pass test filenames to run selected scenarios:
+
+```sh
+ruby -Ilib:test test/run.rb test/core_test.rb test/invocation_test.rb
+```
+
+Release tooling requires Node.js 24.10 or newer and is only used in development
+and CI. Verify its version rules and release cycle with:
+
+```sh
+npm ci --ignore-scripts
+npm test
+```
+
+## An ordinary use case
+
+```ruby
+require "object_framework"
+
+class Greet
+  def initialize(greeting:)
+    @greeting = greeting
+  end
+
+  def call(name:)
+    { message: "#{@greeting}, #{name}" }
+  end
+end
+
+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") # => { message: "Hello, Ada" }
+ensure
+  app.stop
+end
+```
+
+Every operation declares `:none`, `:read`, or `:write` as its transaction policy.
+Transactional operations require a storage adapter. Factories are scoped to an
+invocation, may declare their own dependencies, and may opt into cleanup with
+`close: true`. The reserved `context` dependency exposes a server-generated
+operation identifier and cooperative cancellation. Application registrations
+are finalized at startup. Separate application instances have separate registries.
+
+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
+objects must be converted to values inside the use case.
+
+## Errors and diagnostics
+
+Register ordinary exception classes through `app.errors.register`, supplying a
+category, stable public code, title, and an optional explicit safe-details
+extractor. The closest registered ancestor wins. Unexpected failures receive a
+generic public description.
+
+`FailureReporter` accepts a `sink:` callable. It records one primary failure per
+interaction, plus cleanup failures marked as secondary. Records contain the
+operation identifier, public code, exception and cause classes, backtrace,
+duration, and transaction outcome. Exception messages and input values are
+excluded to avoid exposing credentials or payloads. Applications should apply
+their own retention and access policy to the sink.
+
+Commit outcomes remain `:committed`, `:rolled_back`, or `:indeterminate` when
+the adapter can determine them. A failed commit is never automatically retried.
+Cancellation is cooperative; use cases doing long work should call
+`context.cancellation.check!` at suitable boundaries.
+
+## Contributing
+
+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.
+
+## HTTP order example
+
+```sh
+ruby -Ilib examples/orders/server.rb
+curl -X POST http://127.0.0.1:8080/orders/ready/confirm
+curl -X POST http://127.0.0.1:8080/orders/missing/confirm
+curl -X POST http://127.0.0.1:8080/orders/rejected/confirm
+```
+
+`ConfirmOrder` collaborates with an injected repository. `Order` owns its
+confirmation invariant. An external mapping describes persistence, and an HTTP
+controller normalizes path parameters before invoking the operation. The test
+suite also demonstrates a concurrent commit conflict and an unexpected storage
+failure. The example uses volatile in-memory storage.
+
+HTTP uses a dispatcher with `IO.select` and Fibers, then one new thread per
+admitted request. Admission defaults to 128 active requests. Keep-alive requests
+run sequentially on separate threads. Limits default to an 8 KiB request line,
+32 KiB header section, and 1 MiB body. Header timeout is 10 seconds; body,
+execution, write, and idle timeouts are 30 seconds. Execution cancellation is
+cooperative. `Server` accepts an application-configured OpenSSL `tls_context:`
+with a certificate and private key.
+
+The parser follows [RFC 9112](https://www.rfc-editor.org/rfc/rfc9112.html).
+Ambiguous framing closes the connection. Invalid JSON yields 400, invalid
+structure yields 422, missing routes yield 404, and wrong methods yield 405 with
+`Allow`. Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)
+problem details; presentation and send failures preserve the transaction outcome.
+
+## SQLite
+
+Install the sole optional runtime gem with `bundle install` (or install `sqlite3`
+2.10.1 or newer in the 2.x series). Requiring `object_framework` does not load
+sqlite3 until `ObjectFramework::SQLite` is used.
+
+```ruby
+schema = ObjectFramework::SQLite::Schema.from_mappings(mappings)
+storage = ObjectFramework::SQLite::Storage.new(path: "orders.sqlite3", schema:)
+app = ObjectFramework::Application.new(storage:, mappings:)
+```
+
+Each invocation owns one SQLite connection. Foreign keys are enabled, journal
+mode is DELETE, and synchronization is FULL. Writes use IMMEDIATE transactions;
+reads use DEFERRED transactions. Lock waiting respects the execution deadline
+and a configurable `lock_timeout:` (one second by default). Writes have no
+automatic application-level retries. SQL values are bound parameters; table
+and column names must belong to the declared schema.
+
+Schema version 1 creates the declared tables. Add consecutive versions before
+constructing the storage:
+
+```ruby
+schema.migration(2) { add_column :orders, :note, type: :string }
+```
+
+Migrations run in a transaction and use SQLite's `user_version`. Startup rejects
+newer database versions and mismatched column declarations. DELETE journaling
+can delay a writer's commit while a reader remains active; keep invocations
+short. Call `storage.close` after stopping applications that use it.
+
+## gRPC
+
+Run the same order use case through HTTP and gRPC:
+
+```sh
+ruby -Ilib examples/orders/grpc_server.rb
+ruby -Ilib examples/orders/export_proto.rb > orders.proto
+```
+
+The gRPC service is `orders.Orders/ConfirmOrder`. The framework implements
+HTTP/2, HPACK, proto3 wire encoding, gRPC framing, and trailers in Ruby. Message
+and service descriptors are Ruby objects that export `.proto` contracts.
+Unary, server streaming, client streaming, and bidirectional calls each receive
+one new request thread. Streaming controllers invoke use cases per message or
+batch so that sessions and transactions finish before yielding public values.
+
+Requests default to a 1 MiB message limit, a 32 KiB header limit, 128 active RPCs,
+and 128 connections. Both connection and stream windows bound inbound buffering
+and outgoing DATA. Deadlines and `RST_STREAM` cancellation reach the explicit
+context. Responses carry `grpc-status`, a safe `grpc-message` when needed,
+`error-code`, and `operation-id`. Message compression currently uses identity.
+TLS accepts application certificates and negotiates `h2` through ALPN.
+
+Interop tests use Python grpcio, Google's generated protobuf codec, and
+hyper-h2. They cover every RPC mode, every scalar type, large messages, header
+continuations, error metadata, TLS, admission, deadlines, cancellation, and
+failure after a stream has produced values. Protocol references are
+[HTTP/2](https://www.rfc-editor.org/rfc/rfc9113.html),
+[HPACK](https://www.rfc-editor.org/rfc/rfc7541.html), and the
+[gRPC wire protocol](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md).
+
+## Optional Ruby capabilities
+
+`ObjectFramework::Capabilities::Definitions` wraps Ruby Box. Start Ruby with
+`RUBY_BOX=1`; enabling the variable later cannot change the running VM.
+Separate instances load their own application definitions. Ruby Box remains
+experimental, so the ordinary composition path does not require it.
+
+`Capabilities::IsolatedTask.new(task: YourTask)` runs a class/module's
+`self.call(input)` in a new Ractor. Inputs and results are independent values;
+sessions and execution contexts stay on the owning request thread. Tasks should
+be bounded computations over values. Cancellation is checked before and after
+the isolated task; it does not forcibly terminate a running Ractor.
+
+`ruby benchmark/compare.rb 20000 3` compares interpreter, YJIT, and ZJIT in
+separate processes. See [the benchmark notes](benchmark/README.md) for the
+workload, raw results, and limits of the comparison.

data/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,45 @@
+# Third-party notices
+
+## Documentation fonts
+
+The guides self-host Inter and IBM Plex Mono under the SIL Open Font License
+1.1. Their copyright notices and complete licenses are distributed alongside
+the font files in `docs/assets/fonts/Inter-LICENSE.txt` and
+`docs/assets/fonts/Plex-LICENSE.txt`.
+
+- Inter: https://github.com/rsms/inter, revision
+  `353b61b9f4430d5f420d56605a6e7993e0941470`.
+- IBM Plex: https://github.com/IBM/plex, revision
+  `71f558992315a12ca1f06a2215d57962a1992162`.
+
+The documentation stylesheet is an original implementation of the visual
+reference requested by the project: https://guides.rubyonrails.org/index.html.
+
+## Protocol data
+
+`lib/object_framework/http2/hpack_tables.rb` contains the static header table
+and Huffman code table from RFC 7541, Appendices A and B:
+https://www.rfc-editor.org/rfc/rfc7541.html
+
+Copyright (c) 2015 IETF Trust and the persons identified as the document authors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/examples/guides/01_plain_use_case.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Greet
+  def initialize(greeting:)
+    @greeting = greeting
+  end
+
+  def call(name:)
+    "#{@greeting}, #{name}"
+  end
+end
+
+puts Greet.new(greeting: "Hello").call(name: "Ada")

data/examples/guides/02_composed_application.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+class Greet
+  def initialize(greeting:)
+    @greeting = greeting
+  end
+
+  def call(name:)
+    { message: "#{@greeting}, #{name}" }
+  end
+end
+
+app = ObjectFramework::Application.new
+app.factory(:greeting) { "Hello" }
+app.operation(:greet, use_case: Greet, policy: :none, dependencies: [:greeting])
+app.start
+begin
+  result = app.invoke(:greet, name: "Ada")
+  puts result[:message]
+  puts "Result is frozen: #{result.frozen?}"
+ensure
+  app.stop
+end

data/examples/guides/03_order_domain.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../orders/domain"
+
+order = OrdersExample::Order.new(id: "ready", total_cents: 1500)
+repository = Object.new
+repository.define_singleton_method(:fetch) { |id| order }
+confirm = OrdersExample::ConfirmOrder.new(orders: repository)
+puts confirm.call(order_id: "ready").state
+begin
+  confirm.call(order_id: "ready")
+rescue OrdersExample::OrderNotConfirmable
+  puts "An order can only be confirmed once"
+end

data/examples/guides/04_scoped_resources.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+class Resource
+  def initialize(events:)
+    @events = events
+    @events << "opened"
+  end
+
+  def close
+    @events << "closed"
+  end
+end
+
+class CompareResources
+  def initialize(first:, second:)
+    @first, @second = first, second
+  end
+
+  def call
+    @first.equal?(@second)
+  end
+end
+
+events = []
+app = ObjectFramework::Application.new
+app.factory(:resource, close: true) { Resource.new(events:) }
+app.factory(:first, dependencies: [:resource]) { |resource:| resource }
+app.factory(:second, dependencies: [:resource]) { |resource:| resource }
+app.operation(:compare, use_case: CompareResources, policy: :none, dependencies: [:first, :second])
+app.start
+begin
+  puts "Same resource: #{app.invoke(:compare)}"
+  puts events.join(", ")
+ensure
+  app.stop
+end

data/examples/guides/05_mapping.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "object_framework"
+require_relative "../orders/domain"
+
+mappings = ObjectFramework::Persistence::Mappings.new
+mappings.define(OrdersExample::Order, table: :orders) do
+  field :id
+  field :state
+  field :total_cents, type: :integer
+end
+mappings.validate!
+storage = ObjectFramework::Memory::Storage.new
+write = storage.begin_transaction(mode: :write)
+session = ObjectFramework::Persistence::Session.new(transaction: write, mappings:)
+order = OrdersExample::Order.new(total_cents: 1500)
+begin
+  session.add(order)
+  session.flush
+  write.commit
+ensure
+  session.close
+  write.close
+end
+
+read = storage.begin_transaction(mode: :read)
+session = ObjectFramework::Persistence::Session.new(transaction: read, mappings:)
+begin
+  first = session.find(OrdersExample::Order, order.id)
+  second = session.find(OrdersExample::Order, order.id)
+  puts "UUID assigned: #{!order.id.nil?}"
+  puts "Same identity: #{first.equal?(second)}"
+  puts "Independent session: #{!first.equal?(order)}"
+  puts "Stored state: #{first.state}"
+ensure
+  session.close
+  read.close
+  storage.close
+end

data/examples/guides/06_associations.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "object_framework"
+
+class Customer
+  attr_accessor :id, :name
+  def initialize(id: nil, name:); @id, @name = id, name; end
+end
+
+class Purchase
+  attr_accessor :id, :total_cents, :customer
+  def initialize(id: nil, total_cents:)
+    @id, @total_cents, @customer = id, total_cents, nil
+  end
+end
+
+mappings = ObjectFramework::Persistence::Mappings.new
+mappings.define(Customer, table: :customers) { field :id; field :name }
+mappings.define(Purchase, table: :purchases) do
+  field :id
+  field :total_cents, type: :integer
+  belongs_to :customer, target: Customer, foreign_key: :customer_id
+end
+mappings.validate!
+storage = ObjectFramework::Memory::Storage.new
+write = storage.begin_transaction(mode: :write)
+seed = ObjectFramework::Persistence::Session.new(transaction: write, mappings:)
+customer = Customer.new(name: "Ada")
+purchase = Purchase.new(total_cents: 1500)
+purchase.customer = customer
+seed.add(customer)
+seed.add(purchase)
+seed.flush
+write.commit
+seed.close
+write.close
+
+read = storage.begin_transaction(mode: :read)
+session = ObjectFramework::Persistence::Session.new(transaction: read, mappings:)
+begin
+  query = ObjectFramework::Persistence::Query.new.compare(:total_cents, :gte, 1000).order(:total_cents, :desc).limit(10)
+  loaded = session.query(Purchase, query, load: [:customer]).first
+  puts "Customer: #{loaded.customer.name}"
+  puts "Shared identity: #{loaded.customer.equal?(session.find(Customer, customer.id))}"
+ensure
+  session.close
+  read.close
+  storage.close
+end

data/examples/guides/07_http.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require_relative "../orders/application"
+
+bundle = OrdersExample.build
+bundle.application.start
+begin
+  http = Net::HTTP.new("127.0.0.1", bundle.server.port, nil)
+  response = http.post("/orders/ready/confirm", "")
+  puts "HTTP #{response.code}"
+  puts "Order state: #{JSON.parse(response.body).fetch('state')}"
+ensure
+  bundle.application.stop
+  bundle.storage.close
+end

data/examples/guides/08_errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require_relative "../orders/application"
+
+bundle = OrdersExample.build
+bundle.application.start
+begin
+  http = Net::HTTP.new("127.0.0.1", bundle.server.port, nil)
+  %w[missing rejected].each do |id|
+    response = http.post("/orders/#{id}/confirm", "")
+    problem = JSON.parse(response.body)
+    puts "#{response.code} #{problem.fetch('code')}"
+    puts "Occurrence ID present: #{problem.key?('operation_id')}"
+  end
+ensure
+  bundle.application.stop
+  bundle.storage.close
+end

data/examples/guides/09_sqlite.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "../orders/application"
+
+class GetOrder
+  def initialize(session:); @session = session; end
+  def call(order_id:)
+    order = @session.find(OrdersExample::Order, order_id)
+    { state: order.state }
+  end
+end
+
+Dir.mktmpdir("orders-guide") do |directory|
+  schema = ObjectFramework::SQLite::Schema.new(tables: { orders: { id: :string, state: :string, total_cents: :integer } })
+  schema.migration(2) { add_column :orders, :note, type: :string }
+  storage = ObjectFramework::SQLite::Storage.new(path: File.join(directory, "orders.sqlite3"), schema:)
+  bundle = OrdersExample.build(storage:)
+  seed = storage.begin_transaction(mode: :write)
+  row = seed.find(:orders, "ready")
+  seed.update(:orders, "ready", row.merge(note: "gift"))
+  seed.commit
+  seed.close
+  bundle.application.operation(:get_order, use_case: GetOrder, policy: :read, dependencies: [:session])
+  bundle.application.start
+  begin
+    puts "Schema version: #{storage.schema_version}"
+    puts "Read: #{bundle.application.invoke(:get_order, order_id: 'ready')[:state]}"
+    puts "Write: #{bundle.application.invoke(:confirm_order, order_id: 'ready').state}"
+    check = storage.begin_transaction(mode: :read)
+    puts "Unmapped note: #{check.find(:orders, 'ready')[:note]}"
+    check.close
+    puts "Open connections: #{storage.open_connection_count}"
+  ensure
+    bundle.application.stop
+    storage.close
+  end
+end

data/examples/guides/10_grpc.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require_relative "../orders/application"
+require_relative "../orders/contracts"
+
+bundle = OrdersExample.build
+service = OrdersExample.grpc_contract
+controller = ObjectFramework::GRPC::Controller.new(application: bundle.application, operation: :confirm_order)
+server = ObjectFramework::GRPC::Server.new(application: bundle.application, services: [service], controllers: { confirm_order: controller })
+bundle.application.install(server)
+bundle.application.start
+begin
+  Dir.mktmpdir("orders-grpc-guide") do |directory|
+    contract = File.join(directory, "orders.proto")
+    File.write(contract, service.to_proto)
+    python = ENV.fetch("OBJECT_FRAMEWORK_INTEROP_PYTHON", File.expand_path("../../.venv/bin/python", __dir__))
+    output, error, status = Open3.capture3(python, File.expand_path("../orders/grpc_client.py", __dir__), server.port.to_s, contract, "ready")
+    raise error unless status.success?
+    print output
+  end
+ensure
+  bundle.application.stop
+  bundle.storage.close
+end