torikago 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4067561b7267c62468f0ba974be7a68e536fa620cc25c7356ba643f774bc14d9
+  data.tar.gz: 5ceb5e3693ba1a767a2e93f439384df0d568306beabbbb62efb9538dc807dc79
+SHA512:
+  metadata.gz: 9bbe65e72b673873e80dfc51c64de86a1c3240976ebad98f964d47abdef046b99058dc8f33365d9aba9714e6e2a92685db98737084e7b81bb34cc17321fe37fa
+  data.tar.gz: 6968dad15fcdc9e710819468925d4e5da7778b90d53615d31308fcba9f58a9f99d7a6d6f9082d6091618c480cef96083a7476ea013c07c28d3418e55f0f4d9ef

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 se4weed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.ja.md

@@ -0,0 +1,144 @@
+# torikago
+
+`torikago`は、Railsのmodular monolithでmoduleごとの実行境界を扱うためのgemです。`packwerk`や`Rails::Engine`で構造上の境界を作るだけでなく、`Ruby::Box`を使って実行時の境界も強くすることを目指しています。
+
+`torikago`では、module間の呼び出しを`Torikago::Gateway.call(...)`に集約し、各moduleのPackage APIと呼び出し可能なmoduleを事前に定義します。これによって、意図していないmodule間参照を実行時に防ぎやすくします。
+
+![torikago architecture](docs/image.png)
+
+## 設定例
+
+Rails app側でmoduleを登録します。
+
+```ruby
+Torikago.configure do |config|
+  config.register(
+    :foo,
+    root: Rails.root.join("modules/foo"),
+    entrypoint: "app/package_api",    # optional
+    setup: "config/box_setup.rb",     # optional
+    gemfile: "Gemfile"                # optional
+  )
+end
+```
+
+`config.register`で指定できる主な項目は次のとおりです。
+
+- `root`
+  - moduleのルートディレクトリ
+- `entrypoint`
+  - public APIを探索するディレクトリ、またはその配下のファイル
+  - 未指定時は`app/package_api`
+- `setup`
+  - Box boot前に読み込むsetup hook
+  - monkey patchやbox固有の初期化処理に使う
+- `gemfile`
+  - そのBoxで優先したいgem require pathを解決するためのGemfile
+  - Box cold boot時に、解決したrequire pathをそのBoxの`load_path`先頭側へ追加する
+  - main box側のgem activationに頼らず、module codeからmodule-localなgem versionを`require`できるようにするための設定
+
+module側では、公開するPackage APIと、どのmoduleから呼べるかを定義します。
+
+```yaml
+exports:
+  Foo::ListProductsQuery:
+    allowed_callers:
+      - baz
+```
+
+module自身からの呼び出しとmain boxからの呼び出しは許可されます。`allowed_callers`は、他moduleからの参照だけを制限します。
+
+呼び出し側では、対象のclass名を使って呼び出します。
+
+```ruby
+Torikago::Gateway.call("Foo::ListProductsQuery")
+
+# 引数を渡す場合
+Torikago::Gateway.call("Bar::SubmitOrderCommand", title: "Book")
+```
+
+`Torikago::Gateway.call(...)`は、class名から対象moduleを解決し、そのmoduleのexportされたPackage API定義を確認したうえで、対象Boxの中で`new.call(...)`を実行します。
+
+## Example app
+
+`example/rails-modular-monolith/`に、最小のRails example appが入っています。
+
+## 使い方
+
+### gem本体のテスト
+
+```sh
+bundle exec rake test
+```
+
+### example appのテスト
+
+```sh
+cd example/rails-modular-monolith
+RUBY_BOX=1 bundle exec rails test
+```
+
+### example appの起動
+
+```sh
+cd example/rails-modular-monolith
+RUBY_BOX=1 bundle exec rails s
+```
+
+`Ruby::Box`を実際に有効にするには`RUBY_BOX=1`が必要です。
+
+## CLI
+
+`exe/torikago`からCLIを利用できます。
+
+```sh
+bundle exec ruby exe/torikago --help
+```
+
+主なコマンド:
+
+- `torikago init`
+  - 対話式で`package_api.yml`と`config/initializers/torikago.rb`を生成する
+- `torikago check`
+  - `Gateway.call`とmanifestの整合性を検証する
+- `torikago update-package-api [BOX]`
+  - 設定済みentrypointから`package_api.yml`を更新する
+
+`torikago check`は、`Torikago::Gateway.call("...")`の呼び出しを走査し、
+
+- manifestにそのclassが定義されているか
+- 呼び出し元moduleが`allowed_callers`に含まれているか
+- manifest上のclassに対応するファイルが存在するか
+
+を確認します。
+
+## `RUBY_BOX=1`とbootについて
+
+現状のexample appでは、`RUBY_BOX=1`下でRails bootを安定させるために、いくつか回避策を入れています。
+
+- Bundler pluginを無効化する
+- `tmpdir`を早めに読み込む
+- `RUBY_BOX=1`時は`Bundler.require(*Rails.groups)`を避け、必要なgemを明示的に`require`する
+
+これらは`torikago`の最終形というより、現時点でexampleを安定して動かすための実務的なworkaroundです。
+
+## 現時点の制約
+
+- 初回のBox bootは重い
+  - cold boot時は数秒オーダーのコストが出ることがある
+- `Ruby::Box`自体がexperimental
+  - segfaultや不安定さに遭遇することがある
+- Railsや一部gemとの相性問題がある
+  - とくにVM全体へ影響するglobal-effect gemは、きれいに分離しきれない
+- full `Rails::Engine` confinementを素直にやるのはまだ難しい
+
+代表的な例外:
+
+- `Torikago::DependencyError`
+  - 許可されていないmodule間参照
+- `Torikago::PublicApiError`
+  - manifestに宣言されていないPackage APIの呼び出し
+- `Torikago::GemfileOverrideError`
+  - Box用Gemfileの解決やactivateに失敗したとき
+
+そのため、現時点の`torikago`は「すぐ本番導入できる完成品」というより、modular monolithの実行境界をどこまで強くできるかを探る実装です。

data/README.md

@@ -0,0 +1,142 @@
+# torikago
+
+`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.
+
+![torikago architecture](docs/image.png)
+
+## Configuration example
+
+Register modules from your Rails app:
+
+```ruby
+Torikago.configure do |config|
+  config.register(
+    :foo,
+    root: Rails.root.join("modules/foo"),
+    entrypoint: "app/package_api",    # optional
+    setup: "config/box_setup.rb",     # optional
+    gemfile: "Gemfile"                # optional
+  )
+end
+```
+
+The main `config.register` options are:
+
+- `root`
+  - the module root directory
+- `entrypoint`
+  - the directory, or file under that directory, used to discover public APIs
+  - defaults to `app/package_api`
+- `setup`
+  - a setup hook loaded before Box boot completes
+  - useful for monkey patches or Box-specific initialization
+- `gemfile`
+  - a Gemfile used to resolve Box-specific gem require paths
+  - during Box cold boot, the resolved require paths are prepended to that Box's `load_path`
+  - this is intended to let module code `require` module-local gem versions without relying on main-box gem activation
+
+On the module side, declare the Package APIs you expose and which modules may call them:
+
+```yaml
+exports:
+  Foo::ListProductsQuery:
+    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:
+
+```ruby
+Torikago::Gateway.call("Foo::ListProductsQuery")
+
+# with arguments
+Torikago::Gateway.call("Bar::SubmitOrderCommand", 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.
+
+## Example app
+
+A minimal Rails example app lives in `example/rails-modular-monolith/`.
+
+## Usage
+
+### Run gem tests
+
+```sh
+bundle exec rake test
+```
+
+### Run example app tests
+
+```sh
+cd example/rails-modular-monolith
+RUBY_BOX=1 bundle exec rails test
+```
+
+### Start the example app
+
+```sh
+cd example/rails-modular-monolith
+RUBY_BOX=1 bundle exec rails s
+```
+
+`RUBY_BOX=1` is required to actually enable `Ruby::Box`.
+
+## CLI
+
+Use the CLI via `exe/torikago`:
+
+```sh
+bundle exec ruby exe/torikago --help
+```
+
+Main commands:
+
+- `torikago init`
+  - interactively generate `package_api.yml` files and `config/initializers/torikago.rb`
+- `torikago check`
+  - validate `Gateway.call` 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:
+
+- the class is declared in a manifest
+- the caller module is included in `allowed_callers`
+- the manifest entry has a matching implementation file
+
+## About `RUBY_BOX=1` and boot
+
+The current example app includes a few practical boot workarounds to keep Rails startup stable under `RUBY_BOX=1`:
+
+- disable Bundler plugins
+- load `tmpdir` early
+- avoid `Bundler.require(*Rails.groups)` under `RUBY_BOX=1` and require the needed gems explicitly
+
+These are pragmatic workarounds for the current example app, not a finalized long-term contract for `torikago`.
+
+## Current limitations
+
+- Initial Box boot is slow
+  - cold boot can take several seconds
+- `Ruby::Box` itself is still experimental
+  - 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
+
+Common errors:
+
+- `Torikago::DependencyError`
+  - an unauthorized cross-module reference
+- `Torikago::PublicApiError`
+  - calling a Package API that is not declared in the manifest
+- `Torikago::GemfileOverrideError`
+  - failure while resolving or activating a Box-specific Gemfile override
+
+So, at the moment, `torikago` is better understood as an implementation exploring how far runtime boundaries in a modular monolith can be pushed, rather than a fully production-ready finished product.

data/exe/torikago

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+lib_dir = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require "torikago"
+
+exit Torikago::CLI.new.run(ARGV)

data/lib/torikago/checker.rb

@@ -0,0 +1,159 @@
+require "pathname"
+require "yaml"
+
+module Torikago
+  # Lightweight static checks for explicit Gateway calls and package API
+  # manifests. This is intentionally conservative; runtime enforcement still
+  # lives in Gateway.
+  class Checker
+    Result = Struct.new(
+      :errors,
+      :scanned_file_count,
+      :gateway_call_count,
+      :manifest_count,
+      keyword_init: true
+    ) do
+      def ok?
+        errors.empty?
+      end
+    end
+
+    CALL_PATTERN = /
+      Torikago::Gateway\.call\(
+      \s*
+      ["'](?<class_name>[A-Z][A-Za-z0-9:]+)["']
+    /x.freeze
+
+    def initialize(configuration:, source_roots:)
+      @configuration = configuration
+      @source_roots = Array(source_roots).map { |root| Pathname(root) }
+      @manifests = {}
+    end
+
+    def call
+      errors = []
+      gateway_call_count = 0
+      scanned_files = source_files
+
+      scanned_files.each do |path|
+        gateway_call_count += scan_gateway_calls(path, errors)
+      end
+
+      manifest_count = 0
+      configuration.each_definition do |definition|
+        manifest_count += 1
+        validate_manifest_entries(definition, errors)
+      end
+
+      Result.new(
+        errors: errors,
+        scanned_file_count: scanned_files.size,
+        gateway_call_count: gateway_call_count,
+        manifest_count: manifest_count
+      )
+    end
+
+    private
+
+    attr_reader :configuration, :manifests, :source_roots
+
+    def source_files
+      source_roots.flat_map { |root| Dir[root.join("**/*.rb").to_s] }.sort.uniq
+    end
+
+    def scan_gateway_calls(path, errors)
+      content = File.read(path)
+      call_count = 0
+      content.to_enum(:scan, CALL_PATTERN).each do
+        call_count += 1
+        class_name = Regexp.last_match[:class_name]
+        # Public API names are expected to start with their owning module
+        # namespace, e.g. Foo::ListProductsQuery targets the :foo box.
+        target_box = infer_box_name(class_name)
+        manifest_entry = public_api_entry_for(target_box, class_name)
+        caller_box = infer_caller_box_from_path(path)
+
+        if manifest_entry.nil?
+          errors << "#{path}: #{class_name} is not declared in #{target_box}/package_api.yml exports"
+          next
+        end
+
+        next if caller_box.nil?
+        next if caller_box == target_box
+
+        allowed_callers = Array(manifest_entry["allowed_callers"]).map(&:to_s)
+        next if allowed_callers.include?(caller_box.to_s)
+
+        errors << "#{path}: #{caller_box} is not allowed to call #{class_name}"
+      end
+
+      call_count
+    end
+
+    def validate_manifest_entries(definition, errors)
+      exported_package_apis(load_manifest(definition)).each_key do |class_name|
+        # The manifest is the contract, but the checker also catches stale
+        # entries whose implementation file has been deleted or moved.
+        expected_path = expected_public_api_path(definition, class_name)
+        next if expected_path.exist?
+
+        errors << "#{definition.root.join('package_api.yml')}: #{class_name} does not have a matching file at #{expected_path}"
+      end
+    end
+
+    def public_api_entry_for(box_name, class_name)
+      exported_package_apis(load_manifest(configuration.fetch(box_name)))[class_name]
+    rescue KeyError
+      nil
+    end
+
+    def load_manifest(definition)
+      manifests.fetch(definition.name) do
+        manifest_path = definition.root.join("package_api.yml")
+        manifests[definition.name] =
+          if manifest_path.exist?
+            YAML.safe_load(manifest_path.read, permitted_classes: [], aliases: false) || {}
+          else
+            {}
+          end
+      end
+    end
+
+    def expected_public_api_path(definition, class_name)
+      relative_path = class_name.split("::").map { |segment| underscore(segment) }.join("/")
+      public_api_root(definition).join("#{relative_path}.rb")
+    end
+
+    def infer_box_name(class_name)
+      class_name.split("::").first.downcase.to_sym
+    end
+
+    def infer_caller_box_from_path(path)
+      # This path heuristic matches the Rails modular-monolith layout that
+      # torikago is designed around: modules/<box-name>/...
+      path.match(%r{/modules/(?<box>[a-z0-9_]+)/})&.named_captures&.fetch("box", nil)&.to_sym
+    end
+
+    def exported_package_apis(manifest)
+      manifest.fetch("exports") { manifest.fetch("public_api", {}) }
+    end
+
+    def underscore(name)
+      word = name.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+      word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+      word.downcase
+    end
+
+    def public_api_root(definition)
+      return definition.root.join("app/package_api") if definition.entrypoint.nil?
+
+      # entrypoint may point at either a directory or a single boot file. For a
+      # file entrypoint, package API implementations live next to that file.
+      candidate = definition.root.join(definition.entrypoint)
+      return candidate if candidate.directory?
+      return candidate unless candidate.extname == ".rb"
+
+      candidate.dirname
+    end
+  end
+end