torikago 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4067561b7267c62468f0ba974be7a68e536fa620cc25c7356ba643f774bc14d9
-  data.tar.gz: 5ceb5e3693ba1a767a2e93f439384df0d568306beabbbb62efb9538dc807dc79
+  metadata.gz: 0af7286987b986ed0366120312c488e768ab119e79cf025ea20b8e1e51039878
+  data.tar.gz: 0235edbb0503573d4caaaf702284f75604989d99ccee1cf189cd81a1eb04c178
 SHA512:
-  metadata.gz: 9bbe65e72b673873e80dfc51c64de86a1c3240976ebad98f964d47abdef046b99058dc8f33365d9aba9714e6e2a92685db98737084e7b81bb34cc17321fe37fa
-  data.tar.gz: 6968dad15fcdc9e710819468925d4e5da7778b90d53615d31308fcba9f58a9f99d7a6d6f9082d6091618c480cef96083a7476ea013c07c28d3418e55f0f4d9ef
+  metadata.gz: 06628e161d1f2210bcca6e99f1dd7bb9d5697ed89f863ae351d349ec3844030185a61856e195a4c41cff3605b6d58f818986d21fb14ca8b52948ae68b58c8783
+  data.tar.gz: 35cf7e1d20061c198e7fcf2fcaadd4f9014dc58ed9d08fc4f5307f5ae8ca494ba79599519eaa4747763cef6219594e32c92b128d09e01be9cd4cb188b5dfdf19

data/README.ja.md

@@ -2,7 +2,7 @@
 
 `torikago`は、Railsのmodular monolithでmoduleごとの実行境界を扱うためのgemです。`packwerk`や`Rails::Engine`で構造上の境界を作るだけでなく、`Ruby::Box`を使って実行時の境界も強くすることを目指しています。
 
-`torikago`では、module間の呼び出しを`Torikago::Gateway.call(...)`に集約し、各moduleのPackage APIと呼び出し可能なmoduleを事前に定義します。これによって、意図していないmodule間参照を実行時に防ぎやすくします。
+`torikago`では、module間の呼び出しを`Torikago::Gateway.invoke(...)`に集約し、各moduleが公開するPackage APIのclass・methodと呼び出し可能なmoduleを事前に定義します。これによって、意図していないmodule間参照を実行時に防ぎやすくします。
 
 ![torikago architecture](docs/image.png)
 
@@ -16,6 +16,7 @@ Torikago.configure do |config|
     :foo,
     root: Rails.root.join("modules/foo"),
     entrypoint: "app/package_api",    # optional
+    rails_engine: true,               # optional
     setup: "config/box_setup.rb",     # optional
     gemfile: "Gemfile"                # optional
   )
@@ -29,6 +30,10 @@ end
 - `entrypoint`
   - public APIを探索するディレクトリ、またはその配下のファイル
   - 未指定時は`app/package_api`
+- `rails_engine`
+  - moduleが所有するRails::Engineのroute setを有効にし、Rails runtimeを同じBoxへ読み込む
+  - host routerでは`Foo::Engine`ではなく`Torikago::RackEndpoint.new(:foo)`をmountする
+  - host routeから`Torikago.action(...)`でControllerを呼ぶ場合は不要
 - `setup`
   - Box boot前に読み込むsetup hook
   - monkey patchやbox固有の初期化処理に使う
@@ -42,26 +47,101 @@ module側では、公開するPackage APIと、どのmoduleから呼べるかを
 ```yaml
 exports:
   Foo::ListProductsQuery:
+    methods:
+      - call
+      - execute!
     allowed_callers:
       - baz
 ```
 
 module自身からの呼び出しとmain boxからの呼び出しは許可されます。`allowed_callers`は、他moduleからの参照だけを制限します。
 
-呼び出し側では、対象のclass名を使って呼び出します。
+constructorに引数がない場合は、公開methodを直接指定します。
 
 ```ruby
-Torikago::Gateway.call("Foo::ListProductsQuery")
+Torikago::Gateway.invoke("Foo::ListProductsQuery", :call)
 
-# 引数を渡す場合
-Torikago::Gateway.call("Bar::SubmitOrderCommand", title: "Book")
+# method引数はmethod名より後ろへ渡す
+Torikago::Gateway.invoke("Bar::SubmitOrderCommand", :execute!, title: "Book")
 ```
 
-`Torikago::Gateway.call(...)`は、class名から対象moduleを解決し、そのmoduleのexportされたPackage API定義を確認したうえで、対象Boxの中で`new.call(...)`を実行します。
+constructorに引数がある場合は`build`を使います。`build`の引数は`new`だけへ、`invoke`の引数は指定したpublic methodだけへ渡ります。
+
+```ruby
+Torikago::Gateway
+  .build("Foo::ListProductsQuery", page: 2)
+  .invoke(:execute!, per_page: 20)
+```
+
+対象Box内で`Foo::ListProductsQuery.new(page: 2).public_send(:execute!, per_page: 20)`を実行します。GatewayはBoxをbootする前にclass・method・callerを`package_api.yml`と照合します。private methodは呼べず、constructorや対象methodの例外は包まずそのまま伝播します。
+
+`Gateway.call`は削除されました。`Gateway.call("Foo::Query", value)`は`Gateway.invoke("Foo::Query", :call, value)`へ変更し、manifestへ`methods: [call]`を追加してください。`update-package-api`は既存の`methods`を保持し、新規発見したentryには`methods: []`を生成するため、公開methodを明示的に選ぶ必要があります。
+
+## Root Moduleの定数参照
+
+Registered Moduleから、Railsアプリケーション本体（Root Module）のtop-level定数はmanifestへの宣言なしで参照できます。main boxの同じclass/module objectを共有するため、QueryやCommandの呼び出しだけでなく、継承にも利用できます。
+
+Module namespace内から参照するときは、`::`で始まる絶対定数参照を使います。これにより、`Foo::Order`のtypoがRootの`::Order`へ暗黙にfallbackすることを防ぎます。
+
+```ruby
+# Railsアプリケーション本体
+class Order
+end
+
+class CustomerQuery
+  def self.call(customer_id:)
+    # ...
+  end
+end
+
+# config.register(:foo, ...)されたmodule内
+class Foo::SpecialOrder < ::Order
+end
+
+::CustomerQuery.call(customer_id: 1)
+```
+
+ownershipはtop-level定数単位で判定します。top-level定数の定義元が`config.register(..., root:)`配下なら、その定数は別のModule Boxへ自動公開されません。Root-owned class/moduleは同じオブジェクトを共有するため、そのnamespaceをregistered rootから再オープンして子定数を追加すると、子定数だけを隔離できません。torikagoは検出可能な場合にnamespace全体の共有を拒否しますが、mixed-ownership namespace自体をサポートしません。隔離が必要な定数は、module-ownedなtop-level namespace配下へ配置してください。
+
+Module Box内に同名定数がある場合は、そのmodule-local定数が優先されます。Root ModuleからRegistered Module、およびRegistered Module間の呼び出しには、引き続き`Torikago::Gateway`を使用してください。
 
 ## Example app
 
-`example/rails-modular-monolith/`に、最小のRails example appが入っています。
+`example/rails-modular-monolith-with-rails-engine/`に、Rails::EngineをBox内で動かすexample appが入っています。
+
+```ruby
+# config/routes.rb（host application）
+mount Torikago::RackEndpoint.new(:foo) => "/"
+```
+
+endpointは現在のlazy bootを維持します。最初のHTTP requestまたはGateway呼び出しでmodule Boxを生成し、以降は同じBoxを再利用します。
+この橋渡しにはRack互換のroute endpointを使います。process全体へRack middlewareを
+追加する仕組みではありません。
+
+Controllerの隔離にRails::Engineは必須ではありません。host側のrouteから、
+torikagoがmodule Box内だけで解決するControllerへdispatchできます。
+
+```ruby
+# config/initializers/torikago.rb
+Torikago.configure do |config|
+  config.register(:qux, root: Rails.root.join("modules/qux"))
+end
+
+# config/routes.rb（host application）
+get "/qux/showcase" => Torikago.action(
+  :qux,
+  "Qux::ShowcaseController",
+  :show
+)
+```
+
+Controllerの所有moduleは、`config/initializers/torikago.rb`へ登録したmodule名と
+rootで決まり、このhost route方式のために追加の`config.register` optionは必要ありません。
+ただし、現在のRails integrationでは、実際のController classを登録module名から導かれる
+namespace内に置く必要があります。namespaceを持たないRails Controllerへの対応は
+[issue #15](https://github.com/se4weed/torikago/issues/15)で追跡しています。
+Controller、Model、helper、view、Package APIをhost applicationのautoload pathへ
+追加する必要はありません。
 
 ## 使い方
 
@@ -74,15 +154,15 @@ bundle exec rake test
 ### example appのテスト
 
 ```sh
-cd example/rails-modular-monolith
-RUBY_BOX=1 bundle exec rails test
+cd example/rails-modular-monolith-with-rails-engine
+bundle exec bin/box-rails test
 ```
 
 ### example appの起動
 
 ```sh
-cd example/rails-modular-monolith
-RUBY_BOX=1 bundle exec rails s
+cd example/rails-modular-monolith-with-rails-engine
+bundle exec bin/box-rails s
 ```
 
 `Ruby::Box`を実際に有効にするには`RUBY_BOX=1`が必要です。
@@ -100,15 +180,17 @@ bundle exec ruby exe/torikago --help
 - `torikago init`
   - 対話式で`package_api.yml`と`config/initializers/torikago.rb`を生成する
 - `torikago check`
-  - `Gateway.call`とmanifestの整合性を検証する
+  - `Gateway.invoke`および`Gateway.build(...).invoke(...)`とmanifestの整合性を検証する
 - `torikago update-package-api [BOX]`
   - 設定済みentrypointから`package_api.yml`を更新する
 
-`torikago check`は、`Torikago::Gateway.call("...")`の呼び出しを走査し、
+`torikago check`は、`Ripper`で静的なGateway呼び出しを走査し、
 
 - manifestにそのclassが定義されているか
+- 呼び出すmethodが空でない`methods`配列に定義されているか
 - 呼び出し元moduleが`allowed_callers`に含まれているか
 - manifest上のclassに対応するファイルが存在するか
+- 静的に確認できる場合、公開したinstance methodが実装されているか
 
 を確認します。
 
@@ -130,14 +212,19 @@ bundle exec ruby exe/torikago --help
   - segfaultや不安定さに遭遇することがある
 - Railsや一部gemとの相性問題がある
   - とくにVM全体へ影響するglobal-effect gemは、きれいに分離しきれない
-- full `Rails::Engine` confinementを素直にやるのはまだ難しい
+- Rails integrationにはprocess-globalなframework stateが残る
+  - Rails initializerやnative extensionはBoxごとに完全分離されない
+- 実際のRails Controllerは、現在は登録moduleのnamespace内に置く必要がある
+  - namespaceを持たないControllerへの対応はissue #15で追跡中
 
 代表的な例外:
 
 - `Torikago::DependencyError`
   - 許可されていないmodule間参照
 - `Torikago::PublicApiError`
-  - manifestに宣言されていないPackage APIの呼び出し
+  - manifestに宣言されていないPackage API classまたはmethodの呼び出し
+- `Torikago::BoxUnavailableError`
+  - `RUBY_BOX=1`を指定したが対象Boxを生成・準備できなかった場合。main processへはfallbackしない
 - `Torikago::GemfileOverrideError`
   - Box用Gemfileの解決やactivateに失敗したとき
 

data/README.md

@@ -2,7 +2,7 @@
 
 `torikago` is a gem for introducing per-module runtime boundaries to Rails modular monoliths. It aims to strengthen runtime isolation with `Ruby::Box`, in addition to the structural boundaries you can already get from tools like `packwerk` and `Rails::Engine`.
 
-With `torikago`, module-to-module calls are funneled through `Torikago::Gateway.call(...)`, and each module declares which Package APIs it exposes and which modules may call them. This makes it easier to prevent unintended cross-module references at runtime.
+With `torikago`, module-to-module calls are funneled through `Torikago::Gateway.invoke(...)`, and each module declares which Package API classes and methods it exposes and which modules may call them. This makes it easier to prevent unintended cross-module references at runtime.
 
 ![torikago architecture](docs/image.png)
 
@@ -16,6 +16,7 @@ Torikago.configure do |config|
     :foo,
     root: Rails.root.join("modules/foo"),
     entrypoint: "app/package_api",    # optional
+    rails_engine: true,               # optional
     setup: "config/box_setup.rb",     # optional
     gemfile: "Gemfile"                # optional
   )
@@ -29,6 +30,10 @@ The main `config.register` options are:
 - `entrypoint`
   - the directory, or file under that directory, used to discover public APIs
   - defaults to `app/package_api`
+- `rails_engine`
+  - enables the module-owned Rails::Engine route set and loads its Rails runtime into the same Box
+  - mount `Torikago::RackEndpoint.new(:foo)` in the host router instead of mounting `Foo::Engine`
+  - not required when host routes dispatch controllers with `Torikago.action(...)`
 - `setup`
   - a setup hook loaded before Box boot completes
   - useful for monkey patches or Box-specific initialization
@@ -42,26 +47,105 @@ On the module side, declare the Package APIs you expose and which modules may ca
 ```yaml
 exports:
   Foo::ListProductsQuery:
+    methods:
+      - call
+      - execute!
     allowed_callers:
       - baz
 ```
 
 Calls from the module itself and from the main box are allowed implicitly. `allowed_callers` only restricts calls coming from other modules.
 
-Call a Package API by class name:
+For an argumentless constructor, invoke the exported public method directly:
 
 ```ruby
-Torikago::Gateway.call("Foo::ListProductsQuery")
+Torikago::Gateway.invoke("Foo::ListProductsQuery", :call)
 
-# with arguments
-Torikago::Gateway.call("Bar::SubmitOrderCommand", title: "Book")
+# arguments after the method name go to that method
+Torikago::Gateway.invoke("Bar::SubmitOrderCommand", :execute!, title: "Book")
 ```
 
-`Torikago::Gateway.call(...)` resolves the target module from the class name, checks the exported Package API declaration for that module, and then runs `new.call(...)` inside the target Box.
+Use `build` when the constructor takes arguments. `build` arguments go only to `new`; `invoke` arguments go only to the selected public method:
+
+```ruby
+Torikago::Gateway
+  .build("Foo::ListProductsQuery", page: 2)
+  .invoke(:execute!, per_page: 20)
+```
+
+This runs `Foo::ListProductsQuery.new(page: 2).public_send(:execute!, per_page: 20)` entirely inside the target Box. Before booting that Box, Gateway checks the class, method, and caller against `package_api.yml`. Private methods cannot be invoked and target constructor/method exceptions are propagated unchanged.
+
+`Gateway.call` has been removed. Migrate `Gateway.call("Foo::Query", value)` to `Gateway.invoke("Foo::Query", :call, value)`, and add `methods: [call]` to its manifest entry. `update-package-api` preserves existing `methods`; newly discovered entries use `methods: []` so the public surface must be chosen explicitly.
+
+## Referencing Root Module constants
+
+A Registered Module can reference top-level constants from the Rails application (the Root Module) without declaring them in a manifest. Torikago shares the same class or module object from the main Box, so Root constants can be used for inheritance as well as Query or Command calls.
+
+Use an absolute constant reference beginning with `::` from inside a module namespace. This prevents a typo such as `Foo::Order` from silently falling back to the Root `::Order`.
+
+```ruby
+# Rails application
+class Order
+end
+
+class CustomerQuery
+  def self.call(customer_id:)
+    # ...
+  end
+end
+
+# Inside a config.register(:foo, ...) module
+class Foo::SpecialOrder < ::Order
+end
+
+::CustomerQuery.call(customer_id: 1)
+```
+
+Ownership is atomic at the top-level constant. A top-level constant whose definition is below a `config.register(..., root:)` path is not exposed automatically to another Module Box. Because a Root-owned class or module is shared as the same object, reopening that namespace from a registered root cannot isolate only the newly added child constants. Torikago rejects the whole namespace when it can detect this conflict, but mixed-ownership namespaces are not supported. Put constants that need isolation below a module-owned top-level namespace instead.
+
+A module-local constant with the same name takes precedence. Calls from the Root Module to a Registered Module, and calls between Registered Modules, must still use `Torikago::Gateway`.
 
 ## Example app
 
-A minimal Rails example app lives in `example/rails-modular-monolith/`.
+The Rails::Engine confinement example lives in
+`example/rails-modular-monolith-with-rails-engine/`.
+
+```ruby
+# config/routes.rb (host application)
+mount Torikago::RackEndpoint.new(:foo) => "/"
+```
+
+The endpoint preserves lazy boot: the module Box is created on the first HTTP
+request or Gateway invocation and reused afterward.
+Torikago uses Rack-compatible route endpoints for this bridge; it does not add
+process-wide Rack middleware.
+
+Rails::Engine is optional for controller isolation. A host-owned route can
+dispatch to a controller constant that Torikago resolves only inside the module
+Box:
+
+```ruby
+# config/initializers/torikago.rb
+Torikago.configure do |config|
+  config.register(:qux, root: Rails.root.join("modules/qux"))
+end
+
+# config/routes.rb (host application)
+get "/qux/showcase" => Torikago.action(
+  :qux,
+  "Qux::ShowcaseController",
+  :show
+)
+```
+
+The module name and root registered in `config/initializers/torikago.rb` identify
+the owner, and no additional `config.register` option is required for this
+host-route mode. The current Rails integration still requires real controller
+classes to live under the namespace derived from the registered module name.
+Support for non-namespaced Rails controllers is tracked in
+[issue #15](https://github.com/se4weed/torikago/issues/15). Controllers, models,
+helpers, views, and Package APIs stay under the registered module root; they do
+not need to be added to the host application's autoload paths.
 
 ## Usage
 
@@ -74,15 +158,15 @@ bundle exec rake test
 ### Run example app tests
 
 ```sh
-cd example/rails-modular-monolith
-RUBY_BOX=1 bundle exec rails test
+cd example/rails-modular-monolith-with-rails-engine
+bundle exec bin/box-rails test
 ```
 
 ### Start the example app
 
 ```sh
-cd example/rails-modular-monolith
-RUBY_BOX=1 bundle exec rails s
+cd example/rails-modular-monolith-with-rails-engine
+bundle exec bin/box-rails s
 ```
 
 `RUBY_BOX=1` is required to actually enable `Ruby::Box`.
@@ -100,15 +184,17 @@ Main commands:
 - `torikago init`
   - interactively generate `package_api.yml` files and `config/initializers/torikago.rb`
 - `torikago check`
-  - validate `Gateway.call` usage against manifests
+  - validate `Gateway.invoke` and `Gateway.build(...).invoke(...)` usage against manifests
 - `torikago update-package-api [BOX]`
   - regenerate `package_api.yml` from the configured entrypoint
 
-`torikago check` scans `Torikago::Gateway.call("...")` usage and verifies:
+`torikago check` uses `Ripper` to scan static Gateway invocations and verifies:
 
 - the class is declared in a manifest
+- the invoked method is listed in the non-empty `methods` array
 - the caller module is included in `allowed_callers`
 - the manifest entry has a matching implementation file
+- the exported public instance method is defined when it can be checked statically
 
 ## About `RUBY_BOX=1` and boot
 
@@ -128,14 +214,19 @@ These are pragmatic workarounds for the current example app, not a finalized lon
   - segfaults and instability can happen
 - Some gems do not cooperate well with this model
   - especially global-effect gems that influence the whole VM
-- Full `Rails::Engine` confinement is still difficult to do cleanly
+- Rails integration still relies on process-global framework state
+  - Rails initializers and native extensions are not completely isolated per Box
+- Real Rails controllers currently need the registered module namespace
+  - non-namespaced controller support is tracked in issue #15
 
 Common errors:
 
 - `Torikago::DependencyError`
   - an unauthorized cross-module reference
 - `Torikago::PublicApiError`
-  - calling a Package API that is not declared in the manifest
+  - calling a Package API class or method that is not declared in the manifest
+- `Torikago::BoxUnavailableError`
+  - `RUBY_BOX=1` was requested but the target Box could not be created or prepared; Torikago does not fall back to the main process
 - `Torikago::GemfileOverrideError`
   - failure while resolving or activating a Box-specific Gemfile override