hub_kernel 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 269ad669e7c014af9175190d416dbf7be82bfb8d797eb3a25107bf87b99b1344
-  data.tar.gz: 808639ddaca46f8d8cbe9f187a7d59ae9d50b704f773bf4f255bae731d4339a7
+  metadata.gz: 582093847b3b8cf75dbadd831d8a68df615bebccce57eeb89be12d3496fc89f0
+  data.tar.gz: 4544cb83a72d80f920abbf78f6eee6984b4ab8d28e330d568eb86bd21ef97dc8
 SHA512:
-  metadata.gz: 3c94024970cd0ae83bf695824439a959b6b03061eb39f92268f483ca769fbf323d4210710f805f052028590e65b87a84b43b8801cac1a9b927a9402205f1fd55
-  data.tar.gz: 307661997442f598ee6d2e931540336986a567794113298d496864f86d3ac19e2788ee091e75b8bc9434bd1c61bd3aa1df095b71af29d2479b7898869dfd416b
+  metadata.gz: e5d72c62b32c671f49ae4babcc4755dd871fc4fcfaa35573c78689250ca6b27774bb9ce2db460405940774fc017d1abd742da4df1d646565f8df770d379deb00
+  data.tar.gz: 4d5dff84ef2be0d5ebc3a53ce43e22e42d5d73ad53b0601663139f3fc0a68876e8c874a1833c200d078b29684d0bcd4056f11dd84150c0181dc6462943e9262a

data/README.md

@@ -116,6 +116,36 @@ Supplies.exposed("record_purchase").takes # => [:supplier_id, :bought_on, :lines
 Supplies.exposed("delete_everything")     # => nil
 ```
 
+### Calling an exposed method by name
+An interface such as a JSON API calls a hub through its exposed list, by name, with the
+values a caller sent and the person and account the call is made for:
+
+```ruby
+Supplies.call_exposed("record_purchase", values: { supplier_id: 4, bought_on: "2026-10-01", lines: [] }, person: current_person, account: current_account)
+```
+
+It raises `HubKernel::UnexposedMethodError` for a name the hub does not expose,
+`HubKernel::MissingArgumentError` for a call with no person, no account, or a value the
+method requires, and passes on only the values the method is listed with. A hub raises
+`HubKernel::Refused` with a reason when it will not do what was asked, and the reason
+reaches the caller unchanged.
+
+### The host's permission check and account scope
+Every call by name asks the host whether the person may take the action on the account,
+and runs the method inside the host's scope for that account. The host sets both once
+for the whole app:
+
+```ruby
+HubKernel::Authz.check = ->(person, action, account) { Permissions.allow?(person, action, account) }
+HubKernel::Context.scope = ->(account, &call) { Current.set(account: account, &call) }
+```
+
+The action is named after the hub and the method, such as `supplies:record_purchase`. A
+refused call raises `HubKernel::NotAllowed` before the method runs or its values are
+checked, and a check that answers anything but true or false raises
+`HubKernel::NonBooleanAnswerError`. A call made while either is unset raises
+`HubKernel::UnwiredPortError` naming it.
+
 ### The exposed-list check
 A hub's own test can check its exposed list, so a listed method the hub lacks, or one
 listed with values it does not take, shows in the suite rather than on a caller's
@@ -163,6 +193,9 @@ end
   record its folder is named after, and otherwise to the `host_layer`.
 - The host's layer may name any hub's interface module, and a hub naming another hub's
   interface module is a crossing.
+- The test fails with "The crossing check found no files to read" when none of the files
+  it read belongs to a hub or the host's layer, so a wrong `files:` pattern or an empty
+  map does not pass unnoticed.
 
 ## Installation
 Add this line to your application's Gemfile:

data/lib/hub_kernel/authz.rb

@@ -1,7 +1,10 @@
 module HubKernel
   class NonBooleanAnswerError < StandardError; end
+  class NotAllowed < StandardError; end
 
   module Authz
+    singleton_class.attr_accessor :check
+
     module Vocabulary
       def gates(*actions)
         gated_actions.concat(actions)

data/lib/hub_kernel/conformance/crossings.rb

@@ -17,10 +17,13 @@ module HubKernel
 
       included do
         test "no file names a class another hub owns" do
-          found = (Dir.glob(crossing_files, base: crossing_root) - crossing_exceptions).sort.flat_map do |path|
+          paths = (Dir.glob(crossing_files, base: crossing_root) - crossing_exceptions).sort
+          flunk "The crossing check found no files to read" if paths.none? { |path| the_crossings.belongs?(path) }
+
+          found = paths.flat_map do |path|
             the_crossings.in(path, File.read(File.join(crossing_root, path))).map { |name| "#{path} names #{name}" }
           end
-          flunk found.join("\n") if found.any?
+          assert found.empty?, found.join("\n")
         end
       end
     end

data/lib/hub_kernel/context.rb

@@ -1,5 +1,7 @@
 module HubKernel
   module Context
+    singleton_class.attr_accessor :scope
+
     class Null
       def actor
         :null_actor

data/lib/hub_kernel/crossings.rb

@@ -14,6 +14,8 @@ module HubKernel
       source.scan(/[A-Z]\w*(?:::[A-Z]\w*)*/).filter_map { |name| owned_class_in(name) }.uniq.select { |name| crossing?(name, hub) }
     end
 
+    def belongs?(path) = !owner_of_file(path).nil?
+
     private
 
     def crossing?(name, hub)

data/lib/hub_kernel/exposes.rb

@@ -1,4 +1,12 @@
+require "hub_kernel/action"
+require "hub_kernel/authz"
+require "hub_kernel/context"
+require "hub_kernel/ports"
+
 module HubKernel
+  class UnexposedMethodError < StandardError; end
+  class Refused < StandardError; end
+
   module Exposes
     Exposed = Data.define(:name, :takes, :writes)
 
@@ -8,6 +16,16 @@ module HubKernel
 
     def exposed(name) = exposed_methods[name.to_s]
 
+    def call_exposed(name, values:, person:, account:)
+      raise MissingArgumentError, "A call by name needs a person" if person.nil?
+      raise MissingArgumentError, "A call by name needs an account" if account.nil?
+
+      exposure = exposed(name) || raise(UnexposedMethodError, "#{exposing_hub} does not expose #{name}")
+      refuse_unless_allowed(exposure, person, account)
+      refuse_missing_values(exposure, values)
+      within_account(account) { public_send(exposure.name, **values.slice(*exposure.takes)) }
+    end
+
     def exposure_problems
       exposed_methods.values.filter_map { |exposure| exposure_problem(exposure) }
     end
@@ -18,6 +36,25 @@ module HubKernel
 
     def exposing_hub = name.demodulize
 
+    def refuse_unless_allowed(exposure, person, account)
+      raise UnwiredPortError, "hub_kernel's permission check is not filled" unless Authz.check
+
+      answer = Authz.check.call(person, "#{exposing_hub.underscore}:#{exposure.name}", account)
+      raise NonBooleanAnswerError, "The permission check must answer true or false, got #{answer.inspect}" unless [ true, false ].include?(answer)
+      raise NotAllowed, "#{exposing_hub} #{exposure.name}" unless answer
+    end
+
+    def within_account(account, &call)
+      raise UnwiredPortError, "hub_kernel's account scope is not filled" unless Context.scope
+
+      Context.scope.call(account, &call)
+    end
+
+    def refuse_missing_values(exposure, values)
+      missing = keywords(exposure, :keyreq) - values.keys
+      raise MissingArgumentError, "Give #{missing.join(", ")}" if missing.any?
+    end
+
     def exposure_problem(exposure)
       return "#{exposing_hub} exposes #{exposure.name}, which it has no method for" unless respond_to?(exposure.name)
       return if takes_listed_values?(exposure)

data/lib/hub_kernel/version.rb

@@ -1,3 +1,3 @@
 module HubKernel
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - tylercschneider