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.

Application composition and execution

Start with Application. Register 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; context, session, and transaction are reserved execution dependencies. The latter two require a transactional operation, and sessions require mappings.

ExecutionContext carries a generated operation identifier and 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.

Persistence

Mappings describes ordinary domain objects through 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 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 is immutable. Each filter, comparison, ordering, limit, or offset returns a new query. Queries run with Memory::Storage or the optional SQLite::Storage. SQLite requires the sqlite3 gem; 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 binds method/path patterns to explicit controllers. Install HTTP::Server in the application to serve HTTP/1.1 with bounded admission and request timeouts. HTTP::JSONPresenter formats values; HTTP::ProblemPresenter formats safe error descriptions as problem details.

Protobuf::Message declares proto3 fields and encodes or decodes ordinary hashes. GRPC::Service declares unary and streaming methods and exports their .proto contract. Install 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 before startup. The closest registered ancestor supplies the public category, code, title, and explicitly safe details. Unexpected exceptions receive a generic description. FailureReporter sends immutable diagnostic records to a callable sink without exception messages or input values.

Capabilities::Definitions loads definitions into a Ruby Box when Ruby starts with RUBY_BOX=1. 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.