torikago 0.0.1 → 0.1.0

data/lib/torikago/gateway.rb

@@ -6,8 +6,12 @@ module Torikago
   # manifest before dispatching into the target module container.
   class Gateway
     class << self
-      def call(...)
-        Torikago.gateway.call(...)
+      def build(...)
+        Torikago.gateway.build(...)
+      end
+
+      def invoke(...)
+        Torikago.gateway.invoke(...)
       end
     end
 
@@ -15,24 +19,51 @@ module Torikago
       @registry = registry
       @configuration = configuration
       @manifest_loader = manifest_loader || method(:load_manifest)
-      @manifests = {}
+      @manifests = Hash.new
     end
 
-    def call(public_api_class_name, *args, **kwargs)
+    def build(public_api_class_name, *constructor_args, **constructor_kwargs)
+      Invocation.new(
+        gateway: self,
+        public_api_class_name: public_api_class_name,
+        constructor_args: constructor_args,
+        constructor_kwargs: constructor_kwargs
+      )
+    end
+
+    def invoke(public_api_class_name, method_name, *method_args, **method_kwargs)
+      dispatch(
+        public_api_class_name: public_api_class_name,
+        method_name: method_name,
+        constructor_args: Array.new,
+        constructor_kwargs: Hash.new,
+        method_args: method_args,
+        method_kwargs: method_kwargs
+      )
+    end
+
+    # Internal interface used by Invocation. Validation deliberately precedes
+    # Registry resolution so rejected calls cannot boot the target Box.
+    def dispatch(public_api_class_name:, method_name:, constructor_args:, constructor_kwargs:, method_args:, method_kwargs:)
       target_module = infer_target_module(public_api_class_name)
       caller_module = CurrentExecution.current_box
 
-      # Validation happens before resolving the container so denied calls do not
-      # accidentally boot or load the target module.
-      validate_public_api!(target_module, public_api_class_name, caller_module)
-      registry.resolve(target_module).call(public_api_class_name, *args, **kwargs)
+      validate_public_api!(target_module, public_api_class_name, method_name, caller_module)
+      registry.resolve(target_module).invoke(
+        public_api_class_name,
+        method_name,
+        constructor_args: constructor_args,
+        constructor_kwargs: constructor_kwargs,
+        method_args: method_args,
+        method_kwargs: method_kwargs
+      )
     end
 
     private
 
     attr_reader :configuration, :manifest_loader, :manifests, :registry
 
-    def validate_public_api!(target_module, public_api_class_name, caller_module)
+    def validate_public_api!(target_module, public_api_class_name, method_name, caller_module)
       target_name = target_module.to_sym
       definition = configuration.fetch(target_name)
       manifest = manifests.fetch(target_name) do
@@ -41,7 +72,19 @@ module Torikago
 
       public_api_entry = exported_package_apis(manifest).fetch(public_api_class_name, nil)
       if public_api_entry.nil?
-        raise PublicApiError, "package api export not declared for #{target_name}: #{public_api_class_name}"
+        raise PublicApiError,
+              "package api export not declared for #{target_name}: #{public_api_class_name}##{method_name}"
+      end
+
+      methods = exported_methods(public_api_entry)
+      if methods.empty?
+        raise PublicApiError,
+              "package api methods are not configured: #{public_api_class_name}##{method_name}"
+      end
+
+      unless methods.include?(method_name.to_s)
+        raise PublicApiError,
+              "package api method is not exported: #{public_api_class_name}##{method_name}"
       end
 
       return if caller_module.nil?
@@ -53,7 +96,7 @@ module Torikago
       return if dependency_allowed?(public_api_entry, caller_name)
 
       raise DependencyError,
-            "module dependency not allowed: #{caller_name} -> #{target_name}##{public_api_class_name}"
+            "module dependency not allowed: #{caller_name} -> #{target_name}##{public_api_class_name}##{method_name}"
     end
 
     def load_manifest(definition)
@@ -64,7 +107,7 @@ module Torikago
               "package_api manifest not found for #{definition.name}: #{manifest_path}"
       end
 
-      YAML.safe_load(manifest_path.read, permitted_classes: [], aliases: false) || {}
+      YAML.safe_load(manifest_path.read, permitted_classes: Array.new, aliases: false) || Hash.new
     end
 
     def package_api_manifest_path(definition)
@@ -76,11 +119,29 @@ module Torikago
     end
 
     def exported_package_apis(manifest)
-      manifest.fetch("exports") { manifest.fetch("public_api", {}) }
+      manifest.fetch("exports") { manifest.fetch("public_api", Hash.new) }
     end
 
     def dependency_allowed?(public_api_entry, caller_name)
-      Array(public_api_entry["allowed_callers"]).map(&:to_sym).include?(caller_name)
+      allowed_callers(public_api_entry).map { |caller| caller.to_sym }.include?(caller_name)
+    end
+
+    def exported_methods(public_api_entry)
+      return Array.new unless public_api_entry.is_a?(Hash)
+
+      methods = public_api_entry["methods"]
+      return methods.map(&:to_s) if methods.is_a?(Array)
+
+      Array.new
+    end
+
+    def allowed_callers(public_api_entry)
+      return Array.new unless public_api_entry.is_a?(Hash)
+
+      allowed = public_api_entry["allowed_callers"]
+      return allowed if allowed.is_a?(Array)
+
+      Array.new
     end
   end
 end

data/lib/torikago/invocation.rb

@@ -0,0 +1,26 @@
+module Torikago
+  # Describes one package API invocation without resolving or booting its Box.
+  class Invocation
+    def initialize(gateway:, public_api_class_name:, constructor_args:, constructor_kwargs:)
+      @gateway = gateway
+      @public_api_class_name = public_api_class_name
+      @constructor_args = constructor_args.freeze
+      @constructor_kwargs = constructor_kwargs.freeze
+    end
+
+    def invoke(method_name, *method_args, **method_kwargs)
+      gateway.dispatch(
+        public_api_class_name: public_api_class_name,
+        method_name: method_name,
+        constructor_args: constructor_args,
+        constructor_kwargs: constructor_kwargs,
+        method_args: method_args,
+        method_kwargs: method_kwargs
+      )
+    end
+
+    private
+
+    attr_reader :constructor_args, :constructor_kwargs, :gateway, :public_api_class_name
+  end
+end

data/lib/torikago/package_api_updater.rb

@@ -3,14 +3,15 @@ require "yaml"
 
 module Torikago
   # Regenerates package_api.yml from files under a module's public API
-  # entrypoint while preserving caller permissions already chosen by humans.
+  # entrypoint while preserving exported methods and caller permissions already
+  # chosen by humans.
   class PackageApiUpdater
     def initialize(configuration:)
       @configuration = configuration
     end
 
     def call(module_name = nil)
-      definitions_for(module_name).each_with_object({}) do |definition, updates|
+      definitions_for(module_name).each_with_object(Hash.new) do |definition, updates|
         manifest_path = definition.root.join("package_api.yml")
         existing_manifest = load_manifest(manifest_path)
         updated_manifest = build_manifest(definition, existing_manifest)
@@ -31,21 +32,22 @@ module Torikago
     end
 
     def load_manifest(path)
-      return {} unless path.exist?
+      return Hash.new unless path.exist?
 
-      YAML.safe_load(path.read, permitted_classes: [], aliases: false) || {}
+      YAML.safe_load(path.read, permitted_classes: Array.new, aliases: false) || Hash.new
     end
 
     def build_manifest(definition, existing_manifest)
       existing_public_api = exported_package_apis(existing_manifest)
 
-      public_api_entries = discover_public_api_classes(definition).each_with_object({}) do |class_name, entries|
-        existing_entry = existing_public_api.fetch(class_name, {})
+      public_api_entries = discover_public_api_classes(definition).each_with_object(Hash.new) do |class_name, entries|
+        existing_entry = existing_public_api.fetch(class_name, Hash.new)
 
-        # update-package-api owns discovery, not policy. Keep allowed_callers so
-        # the command does not silently widen or narrow module dependencies.
+        # update-package-api owns discovery, not policy. Keep methods and
+        # allowed_callers so the command does not change the public surface.
         entries[class_name] = {
-          "allowed_callers" => Array(existing_entry["allowed_callers"]).map(&:to_s)
+          "methods" => exported_methods(existing_entry),
+          "allowed_callers" => allowed_callers(existing_entry).map { |caller| caller.to_s }
         }
       end
 
@@ -53,7 +55,25 @@ module Torikago
     end
 
     def exported_package_apis(manifest)
-      manifest.fetch("exports") { manifest.fetch("public_api", {}) }
+      manifest.fetch("exports") { manifest.fetch("public_api", Hash.new) }
+    end
+
+    def allowed_callers(manifest_entry)
+      return Array.new unless manifest_entry.is_a?(Hash)
+
+      allowed = manifest_entry["allowed_callers"]
+      return allowed if allowed.is_a?(Array)
+
+      Array.new
+    end
+
+    def exported_methods(manifest_entry)
+      return Array.new unless manifest_entry.is_a?(Hash)
+
+      methods = manifest_entry["methods"]
+      return methods.map(&:to_s) if methods.is_a?(Array)
+
+      Array.new
     end
 
     def render_manifest(manifest)
@@ -62,8 +82,9 @@ module Torikago
         #
         # Each key under exports is a class that may be called through:
         #
-        #   Torikago::Gateway.call("ModuleName::SomeQuery")
+        #   Torikago::Gateway.invoke("ModuleName::SomeQuery", :call)
         #
+        # methods lists the public instance methods exposed through Gateway.
         # allowed_callers lists other modules that may call that export. The
         # host app and the module itself are allowed implicitly.
         #

data/lib/torikago/rack_endpoint.rb

@@ -0,0 +1,23 @@
+module Torikago
+  # A host-owned Rack endpoint that forwards requests to a registered module
+  # without exposing the module's Rails::Engine or controller constants in the
+  # main Box.
+  class RackEndpoint
+    def initialize(module_name, registry: nil)
+      @module_name = module_name.to_sym
+      @registry = registry
+    end
+
+    def call(env)
+      registry.resolve(module_name).call(env)
+    end
+
+    private
+
+    attr_reader :module_name
+
+    def registry
+      @registry || Torikago.registry
+    end
+  end
+end

data/lib/torikago/registry.rb

@@ -4,7 +4,7 @@ module Torikago
   class Registry
     def initialize(configuration:, &container_factory)
       @configuration = configuration
-      @containers = {}
+      @containers = Hash.new
       @container_factory = container_factory || method(:build_container)
     end
 
@@ -26,8 +26,10 @@ module Torikago
         name: definition.name,
         module_root: definition.root,
         entrypoint: definition.entrypoint,
+        rails_engine: definition.rails_engine,
         setup: definition.setup,
-        gemfile: definition.gemfile
+        gemfile: definition.gemfile,
+        registered_roots: @configuration.each_definition.map(&:root)
       )
     end
   end

data/lib/torikago/root_constant_resolver.rb

@@ -0,0 +1,69 @@
+require "pathname"
+
+module Torikago
+  # Resolves top-level constants from the main Box while keeping constants
+  # owned by registered module roots private to their respective module Box.
+  class RootConstantResolver
+    UNRESOLVED = Object.new.freeze
+
+    attr_reader :unresolved
+
+    def initialize(registered_roots:, main_box: Object)
+      @registered_roots = registered_roots.map { |root| normalize_path(root) }
+      @main_box = main_box
+      @unresolved = UNRESOLVED
+    end
+
+    def resolve(name)
+      return unresolved unless main_box.const_defined?(name, false)
+      return unresolved if registered_source?(main_box.autoload?(name, false))
+
+      source_location = main_box.const_source_location(name, false)
+      return unresolved if registered_source?(source_location&.first)
+
+      constant = main_box.const_get(name, false)
+      return unresolved if constant.is_a?(Module) && registered_descendant?(constant)
+
+      constant
+    end
+
+    private
+
+    attr_reader :main_box, :registered_roots
+
+    def registered_source?(source_path)
+      return false unless source_path
+
+      normalized_source = normalize_path(source_path)
+      registered_roots.any? do |root|
+        normalized_source == root || normalized_source.start_with?("#{root}#{File::SEPARATOR}")
+      end
+    end
+
+    def registered_descendant?(namespace, visited = {})
+      return false if visited[namespace]
+
+      visited[namespace] = true
+      namespace.constants(false).any? do |name|
+        autoload_path = namespace.autoload?(name, false)
+        next true if registered_source?(autoload_path)
+
+        source_location = namespace.const_source_location(name, false)
+        next true if registered_source?(source_location&.first)
+        next false if autoload_path
+
+        child = namespace.const_get(name, false)
+        child.is_a?(Module) && registered_descendant?(child, visited)
+      rescue NameError
+        false
+      end
+    end
+
+    def normalize_path(path)
+      expanded_path = Pathname(path).expand_path
+      expanded_path.exist? ? expanded_path.realpath.to_s : expanded_path.to_s
+    rescue SystemCallError
+      expanded_path.to_s
+    end
+  end
+end

data/lib/torikago/version.rb

@@ -1,3 +1,3 @@
 module Torikago
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/torikago.rb

@@ -2,10 +2,14 @@ require_relative "torikago/configuration"
 require_relative "torikago/current_execution"
 require_relative "torikago/checker"
 require_relative "torikago/cli"
+require_relative "torikago/controller_endpoint"
+require_relative "torikago/root_constant_resolver"
 require_relative "torikago/engine_container"
 require_relative "torikago/errors"
+require_relative "torikago/invocation"
 require_relative "torikago/gateway"
 require_relative "torikago/package_api_updater"
+require_relative "torikago/rack_endpoint"
 require_relative "torikago/registry"
 require_relative "torikago/version"
 
@@ -31,6 +35,10 @@ module Torikago
       @registry ||= Registry.new(configuration: configuration)
     end
 
+    def action(module_name, controller_name, action_name)
+      ControllerEndpoint.new(module_name, controller_name, action_name)
+    end
+
     def version
       VERSION
     end